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REVIEW 


By Ron Davis 


Book Review: 3D Game Engine Design 


lliere nre a !nt of game programming (looks out ificru- 
They use many (JifTcrcni meiliodologies to teach you Siimething 
aliKiut game prognimming* JD Game Engine fMJst}/}} l>y Davit! H. 
Hiierly Is a specialize gniphic algorithm Ixiok. As llie autlior says 
in liis inlroduclkm, most graphic algorithm liiioks either show 
you ctxle k> implement games, or they give you in-depth 
(li.sciission of' 51 ) algorithms that aren't rcally useful for the game 
programmer. I’his liook is in the middle. It is a deep reference 
of 51) programming, liui it ftK uses on the things you need for 
the real tinte gmphics of games. 

I have to confess irmch of the math in ilhs book was 
over my head. It isn't for those of us who didn’t pay enough 
attention to those calculus classes. If this sentence from the 
inlroduciion of the book scares you, the botik isn’t for you: 
“It is assumetl that the reader’s background includes a Inisic 
understanding of vector and mairix algebra, linear algebra, 
muliivariate calculus ant! data structures.'’ 

Kven given that caveat I tleived on into the (xxik. It is first 
and foremost a reference. Each aspect of 51^ engine 
development is ctivered, with no one [>art being dependent on 
atuiihcT. If you do this kind of develtipmenl, you need this (xxik 
on your Ixxik slielf. There is also a CD that comes with the 
Ixxik that includes u full 3D graphic engine, but, alas, it is not 
very Mac frientlly. 

The first chapter is an introduction tf> the btKik and how 
it is organized. The second cha]>ter discusses getimelrical 
methods used lo map three dimensional objects ontti a two 
dimensional screen, including trunsformations, coordinate 
systems, quuternions, Euler angles and distance methods. 
There is also a discussion of eomiiiun slia[ies like splieres, 
capsules, c'ylinders etc. 

Chapter 3 disttisses the graphic' pipeline, which is how a 3D 
game works, including (X'rsfX^ctive fiRijcciion, c'arnera iruxlels, 
c:ulling and clipping. 'Iltere is also a dLscussion of surface and vertex 
attributes indudtng texture's, lighting, traasp;irency and fog, 
Acxxirding to the summary at liie end of the chapter, all of this 
infonnation is not needed if you are using a 3D API like Opt-nCil.. 


No matter what you use for a render, you wall have to 
organize the seene ytiu are going to feed the rendered ’Die book 
Ix'gias a discussion of liiese issues with Chapter 4, Hierarchical 
Si'ene Representations. It discusses means of organizing objects 
so diey are grouped allowing for easier transfomtaiion, eollision 
detection, rendering and jiersisience. 

Picking is the subject of Chapter S, which is tlie means of 
translating a dick on ihe sc men to a 51) objeLt in the scene. The 
author takes a more generalized approadt and handles collision 
detection from any 21) point ftir a ray into liie 3D world. Tlris 
allows for determining if things like laser beams hit 3D objects. 

Chapter 6 covers collision detecaion. ’['he author notes 
this can be a very ctxnplex jiroblem and iliai much of the 
code a game can he taken up with it. He notes at the 
l>eginning of the chapter tliat this needs to be taken into 
account at design titne. The rest of the chapter is dedicated 
to coHlsioas of various types of objects. 

Chapter 7 c overs curves which may not at first be obviously 
used in games, but whitii the anlhor disnis.ses anyway. This 
leads to surfaces in Chapter 8, which are a gnwing pan of 30 
game engines. Tlie chapter covers diff'erenl kinds of curves and 
how^ to subdivide them. 

Chapter 9 is a short diafger on antmaiion covering key 
fnime animation, inverse kinematics and skinning. Hie author 
discusses how' lo create diftcRmt levels of detail in a 3n scene 
on demand in chapter H). 

One of the cooler things in 3D to me is terrain generation 
and that is topic of c hapter 11. He discusses an algorithm used 
to minimize tlie amount of data and calciilaiions needed to 
render landscapes. 

The last two chapters of the Ixxik cover spatial sorting 
lechniques and special effects. Tfie fx^ok concludes with an 
appendix on object oriented infrastructure and numerical 
rnethexLs a.s wells as a complete glo.ssary. 


Ron Davis is :t long linie M:idnUJsh Software Engineer, having workeil for companies like Apple, and Melmwerks on a variety of prodiitts from 
developifient tools to anti-vtnis stifiwarc. 
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HANDHELD 

TECHNOLOGIES 


By Danny Swarzman 

TicTacPalm 


Getting started with Palm OS 


PRtlACI: 

Dcvelopin^^ a Palm OS application comes naturally to a Mac 
programmer. You find familiar notions like resources, liandle- 
hased tnemory and an event lot>p. Yt)U can use QideWarrior for 
Palm OS as the development environment. 

Tills article presents a simple Palm OS application, 
TicTacPalm, which illuslrales the main fealiires of a Palm OS 
application. This application simply plays Uc lac ii)e against 
the user. 

The Palm OS Envikonment 
The Palm Device 

Tlie PaltTi 0[x.Taiing System, Palm OS, is u.sed in a growing 
niiiTil>er of products made l>y different manufacturers including 
Palm, HantLspriag and Sony. 

Tlie screen is typically divided into a 160x160 pixel display 
area, althougli at least one new tlevtce has a slightly longer 
screen. (Kemember when Inside Macinujsh admonished 
develoix'rs not to make assumptions alKiiit a fixed screen size? 
'I'hat advice fiolds true for Palm OS as well.) An application can 
detect stylus activity in lliis area. Tlie stylus can alsf> fx! used to 
enter characters in l^alm*s custom cursive writing system, 
in the area just l>c‘low the tlisplay. All stylus raps enter the system 
event <|ueue as discrete jxai events, similar to the mouse events 
you art! familiar with in Mac OS. The graffiti input ct^ines in tlie 
form of graffiti events. 

Applications are loaded into the device by the 
synebronizirt^ with a desktop computer Uirougii a serial pod or 
IK commimicatitin. This is the standard way for a Palm device 
user to install your program. Some types of j^rograms may lx 
tlownloadcd via a network coniieaion, Imt we wtm'i consider 
that af)proaclt here. 
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figure L A typicai Fabn deiHve. IIk* Ali/Akalion iMumher 
progntm [mmik'S the ofet on a Palm F\*pke. 


Launching and Running Applications 

ihe device shown in Figure I is displaying the equivalent 
of a desktop, lapping an icon brings an upplicalioii to the front. 
From the u.ser's point of view, all applications are always 
running. When an application is brtJUght to the fTOOt, it looks 
exactly like it did the last lime it was in front. 

An application must give up its temporary memory and 
close down each time another appltcaiion comes to the front. 
11ie closing upplicatioti can store infoniiaiion about the partially 
completed cIcKument or tnin.saciion prior to closing. Liter, when 
the application is activated again it can read the stored 
tnfcmiiation and restore the [program state. A special daiaba.se is 
used for this purpose, the pn^'erences. 'lliere are funciions in tlie 
AFI designed specificrilly for reading and writing preferences, 
greatly simplifying the tusk. 


Danny Sw-arznian writes progniim in javaSt ripi, C++ and other languages. He also plays Co and grows I'MHatoes. Contact him with cuinnients 

and job offers. m:ulto:danny.s®stt>wlake.com, ]mp://www,stowlakex'Ofn 
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Forms 

Like a window on a desktop system, a Palm OS Fonn objet-i 
occaipies an areii of the screen. Due to the small screen sizes on 
current devices, many forms use the entire visible area. An 
application may have several forms and switch lx!iween them in 
respK)nse to user actions. At any given time, one form is in front 
and inieracting with iJje u-ser. 

In Palm OS parlance, a uiniiow is any entity in which 
drawing tKatrs. Both forms and offscreen liitmaps are windtiws. 
Offscreen liitmaps allow you to create a composite image and 
then transfer it flickepfree to the screen. 

Using Constaicfor, the GUI design tool included witli 
CodeWarrior for Palm OS, you can create forms and populate 
them with controls. Qmlrols include buttons, checkboxes, lists, 
etc. Kach control is identified by a symbol or name ihai you 
s[K‘cify. Kach name will lie included in the auto-generated 
resource file along with a numeric e([uate. For example, suppose 
you have a button named New on the fonu named GameBoard. 
In the generated header file, Constructor inserts a ^define for the 
synilx)! GameBoardNewButton. Its value is the numeric ID of the 
button. Using the synilx)! (and not ilie numeric value) in your 
source code makes the code easier to read and understand, 

ControLs and Gadgets 

Controls include interface elements such as buttons, Liliels, 
fields, ck\ For most controls, there is a standard Ixdiavitir 
provided by the 09>. The exception is the grfrfee/, The 
application defines a gadget s behavior, responding when the 
stylus enters its area and drawing its contents. Most of the lime 
you can use the pre-huilt controls, and use gadgets only when 
custom appearance or Ixhavior is retjuired. 

Memory 

Palm OS uses a liandle-based meuK^ry management 
system. The.se handles can't be treated as fxiinters to pointers, 
as is done in Mac OS. Instead, to reference data a program first 
locks a handle. The haiidle-kjcking function returns a pointer to 
the data. You can then use the pointer to iransrer data to or 
from the area. Hemeinber to unlock the handle when you are 
done using it, or heaji fragmentation may result. This becomes 
even more of an issue on older devices with less memory. If 
you are aiming for compatibility with older devices and/or older 
versions of Palm OS, take a close look at the available dynamic 
heap space versus your program's requirements. The issue 
exists in a less severe form on mfxlern devices and versions ol' 
the operating system. 

Events 

rhe operating system maintains a queue of events. 
Whenever the system requires the services of an application that 
has Ixxai latmcljed, it sends events to the application. 

For many event.s there is a standard response. When the 
user presses the stylus on the menu bar, the sccjocnce of .stylus 
eveitLs is interpreted as a menu command. The menu command 


then becomes a new event dial is placed in the queue. 

Some events will appear in your application's event handler, 
but arc* really intended for the system. You can ensure that your 
application hands events lo the appropriate Palm OS functions 
by retaining the AppEventLoop exactly as provided in the 
Starterepp , part of the template code that is generated when 
you build a new project. 

Everything relating to your application from launch to 
“shutdown^ will arrive in the form of events. For example, at 
launch time an application-defined fiinaion, called from the 
main event loop, processes a rec|uesl to load a form, I'hat 
function assigns a callback function to the form to assist in the 
handling of events ocTurring in controls in that fomi. Once llie 
form is loaded the call}>ack function hantlles subsequent events. 

A gadget, the custom user interface object discu.ssed earlier, 
can liave a t'alll>ack function too. *rhe application assigns a 
callback to each gadget when ihe form is opened Ihis is how^ a 
gadget responds to s7stem reejuests to draw itself, and to handle 
taps in the gadget, 

DlEVtiOFUMti FOR PALM OS 
CtKleWarriof and Alternatives 

The viLsi majority of applications are developed using 
CtxleWarrior However, the ofTit'ial Palm SDK, available on the 
Palm web site, works with many development environments. 
Otlier lools that are available to create Palm applications include 
a gnu compiler and a translator from Java bytecode to assembler 
for the handheld. 

The .sample code in this article was develo|X^d using 
CodeWarrior for Palm OS, Version 7. It comes with everything 
you need to develop for Palm OS 3-5, including the Palm SDK 
and related documentation. Current devices run Palm OS 3-5 
and Palm OS 4.0, all hough with proper attention to detail you 
can build an applicatUm supptming earlier versions of the 
operating system. 

The CtxleWarrior package includes two disks ^ one to 
develop on the Mac, one to develop on Windows, Ihe sample 
ctxle accompanying this article was developed on the Mac. 

Cxeating a Project 

Use the New command IVoin ij)e File menu. In the dialog 
that a [Spears, enter a name for the new j^roject and choo.se Palm 
OS 5 3 Stationary. 


8 


TicTacPaw 


MACfTECK • Ai'Kil 2002 






Figure 2 Creafing the fmtjccl in QMieWarrior. 


A second dialog will appear, giving you a few choices for 
the template project. For the s^implc axle, Palm OS C++ App 
was used. CodcWarrior then generates a 'Starter' project. This 
project produces a do-nothing applic'atton to use as a framework 
on which to build. You need to rename some things if your 
pR)jecfs name isn’t to lx* 'Starter'. 1 just replaced every 'Starter' 
occurrence with ‘TicTacPalm' in the crxie, tile names, etc. 

Conslruclor 

Cr)!Tstrucror for Palm is an interactive resottrce editor 
included with Code Warrior for Palm. Constructor mattes a 
collection of restmrces that contribute to die apfxarance of the 
application, including menus, forms and icons. In addition to 
editing a restnirce file, Coastnjctor generates a header file that 
defines syml>ols for all the resources in tfie resource file. 
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Debugging, Simulator and POSE 

A ?t\lm application can am in one of these environments: 

• tlie l^alni 0(KTUung Syslcm Bmulator (POSE) 

• the Simulator 

• the device itself 

T he sample project, like the Starter project has two targets: 
TicTacPalm and TtcTacPalTnSim. 

TicTacPalm generates a Palm OS application thai can lie nm 
in POSE or on an actual device. CodeWarrior provides a Palm 
OS debugger to step through the object code for this target. 

For the TicTacSim target^ a collection of simulator 
libraries is included in the project. When the project is l>uilt, 
a MacOS application is created. CodeWarrior’.s MacOS 
debugger can be used to step through this application. This 
is the easiest way lo debug. There are liini Lai ions Lt} this 
approach in that you donT have access to other applications 
or permanent data, which is not significant for our game 
project, but may l>e an issue for m{)re complex applications. 

T here are a couple of strange rituals that you need to EjIIow 
when using the simulator, 'file First time you run a pn>gram with 
tlie simulator, a dialog asks you to find the resources File. You 
must locale :CW for Palm OS Platform 7.0:Metrowefks 
CodeWamiorrPalm OS Support:Simula1or:SystemResources. You 
may notice that the simulator window sticks to the menu bar on 
your screen. To fix that, remove the Palm OS Simulator Preference 
File from the System Folder's Preferences subfolder. You only 
need to do these things once or twice when you are first using 
the product. 

Most of the time, POSE is Lite preferred del rugging plaLfonn. 
POSE is a desktop application that emulates the entire Palm OS 
device, fl alhrws you to switch between a implications, iind even 
retain information belwcxm nms. You set up POSE to emulate a 
particular Palm OS device by copying the ROM from your device 
or by getting the ROM llle for anothc^r device from the Palm wel> 
site, T1ie POSE application must be running when you run the 
TicTacPalm target. Use the CcxieWarrior debugger for Palm OS 
with lliis target. 

Debugging while running on the device itself is possible 
but less convenieni. It wasn’t needed for the sample 
ajjplication. When the code works in simulation, load the ,prc 
file onto the device as you would any Palm application. 

UsH«\ View of TH/TAfiPAiAi 

Forms 

TicTacPalm includes these fonns: 


Most of tlie action cxcurs on the g<iTiie !x>ard (see Figure 4). 
Tlie user laps on a square to make an 'X' move. The pnogmin 
responds by playing an 'O'. There are two buttons: New causes the 
Game Info dialog to lx displayed, while Clear em.ses all tlie plays. 


TEcTaePaim Rpp 


IWy Good Game 

[ New^ 



Figure 4 Ihe game board. 

Tilt: game information form has one field for the user to 
enter a name for the game. There is an OK button and a Cancel 
l>uUon. OK starts a new game with the name in the name field. 
Cancel returns to the game board without altering the name or 
the position. 


Start Neiu Game 


Game Name: My Good Game 


[ Cancel ] [ OK ] 

Figure 5- (lame info form. 

The About form is a modal dialog that appears in response 
to ihe About menu command. 


Start Neui Gome 
r ntout TicTacPalm 


TicTacPalm 

Version 1.0 

by Doryny Sworzman 
Deicribed in MocTech Magazine 
http:/ywww.3towlake.com 
danny^^towtake.com 


• C}ame Board Figure 6. 'Ihe About form. 

• CJame Info 

• About 
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A New System Has Arrived. 



No Mac is complete without Timbuktu Pro, 
the premier remote control and file transfer 
software for Mac OS for over ten years. 

No network is complete without the smart 
systems management of netOctopus. 


Both tools are newly rewritten for OS X, 
bringing the power and simplicity of Netopia 
software to the world’s most advanced 
operating system. For deployment, training 
and support of all your Macs (and PCs!) 
Timbuktu and netOctopus are indispensable. 


Are you ready to migrate? We*re ready to take you there. 

macosxready.com 



Timbuktu Pro’ netopia 












llNSlOl^ TicTacPalm 

Source FUes 

The source files are organized Inio three siil^groups: 

• A[)pl [cation 

• User interface 

• Game 


..^ |^TicT<i€Palm.mcp 

Pifl 

•i^rtcTacPalm ^ 

b| 

^<5| 


3 | 

f Files\/' Segments VTargetsX 


File j Code | 

Oete 

, 1 


^ P^lm OS Oeirice 

0 

0 

© 

* 

^ Ci Resoarws I 

UK 

420 » 

m 


MSL Rgnlime P^lin 12282 

420 • 

© 


> PAlm OS SimalA... 

0 

0 

© 


QL Source 

7K 

262 • * 

© 


^ User interface 

3K 

190 * * 

s 


CGameSoardFo... 

590 

28 • • 

© 


13 CSquareGadget.... 

708 

74 * • 

© 


CGamelnfoForm... 

684 

28 • • 

© 


13 LGadget.cpp 

742 

24 • . 

0 


LForm.cpp 1G16 

36 • • 

s 


T7 Same 

3IC 

60 • * 

© 


J] CT kcTacGame .cpp 1208 

12 * * 

© 


13 CTioTaoEngine.cp 2220 

43 • • 

© 


^ Ci Application 1 


12 ♦ • 

© 


13 TicTad='alm.cpp 

888 

12 • # 

© 


13 TIcTaoPalmftso,.. 

n/a 

xi/a 

© 


'V Tic Tac Resource 

0 

0 « 

s 


B TlcTacP4{m.r£rb 

n/a 

n/d • 

s 

▼ 

15 files 

18K 

682 


4 


figure Z We TicTacPahn Projccl. 


Application 

When yoii generate a project using the prc^ject stationary, 
one u\ llie files, Starter.cpp, contains the main program for the 
application, hi the sample application, Starter.cpp is replaced by 
TicTacPaIm.cpp. Ir ha.s seven functions: 

• AppHandleEvent 

• AppStart 

• AppStop 

• RomVersionCofnpatibie 

• AppEventLoop 

• TicTacPalmMaifi 

• PilotMain 

'I'he contents of the fir.st three are new in TicTacPalm.cpp. Of 
the other four, only TicTacPalmMain jjas lieen c hanged from the 
original StarterMain in Starter.cpp. One line of StarlerMain has 
been comnicnted out. 

FrmGDtoForm ( MairsFcirro ): 

In the sample application, the first form is loaded in 
AppStart rather than tlie main program. 


rhree variables of file scope are defined in TicTacPalm.cpp. 
Their referenced oljjecLs are created in AppStart and deleted in 
AppStop. They are: 

static CGameBoardForm *fGame Board Form = NULL; 
static CGamelnfoForm *fGamelnfoForm = NULL; 
static CTlcTacGame *fGame - NULL; 

Tlie first two handle llic two different forms. The game 
objea contains all the data about the current game that is in 
dynamic KAM. Each of the form objects is initialized with a 
pointer lo the game. 

AppSLlIt 

ff static 

Err AppStact(void) 

I 

UI11LI6 

TicTacPalinPreferenceType preferences: 

// Read tlie saved prcfcncncts / iiiivtd^tate inftjnnatitjn. 
fGaina = new CTicTacGame (): 

fGameBoardForm = new CGanieBoar<iForni ( fGame ) ; 
fGarneTtifoFDrm " new CGaJnoTnfoForm ( rCduie ); 

pryfsSizt' = sizeof {TicTacPalmPreferenceType): 
if (PrefGetAppPreferencestappFiieCreator. appPrefID. 

^preferences. &prefsSize, true) !- tioPrefereneeFound) 
i 

fGame->SetPrefs ( fiipreferenoes )r 
I 

// Display tile first form, 

FrtnC0 1 aForm { f Game - >Ge t F0 rm {) ): 
return errNone: 


lifting /. AppStart 

The preferences record stores information used to reconstmet 
the last state of the progmm so that it will appear to the user that 
the prognim wasn't interrupted at all. If thea" is no preferences 
recorti to read, a default preferences record ts constnicted. 

AppStart cmates fGame and initializes it with the values in 
the preferences. It then brings forward a form, chosen according 
to tlie last state £>f tlie application as recorded in the preferences. 

AppHandleEvent 

// staiic 

Bonlnan AppHandleRvpnt (RventPrr evuntP) 

I 

relurn eventP )eType = frmLoadEvent 

LForin : : Load ( (?veniP->data.frniLo^d. totraiD ): 

I 

Listing 2. Appflanclleliimt 

AppHandleEvent sends the load event to the LForm class 
(which is discussed later). 

App!jtop 

// Sliitic 

void AppStop(void) 
t 

FnnCloseAllForiiiE () ; 

TiGTacPalmPreferenc^iType preferenced i 
fGame->G<; tP refs C ^preferences )r 
PrefSelAppPrefcrenees (appFileCrentor, appPreflD, 
appPrerVersionNum. ^preferences. 
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Your Data Isn’t 
an Important Part 

of the Job 

— It IS the Job. 



"/ con stick 
my entire 
hard drive 
onto a tape 
7 times 
—that’s just 
plain cool!” 




Other backup media, such as CD-RWs and DVD-RAMs, 
simply can't compare to VXA-1 tape technology when it 
comes to capacity transfer rate and overall price. 

Fastj economical and easy-to-use, 

VXA FireWire offers: 


The High-Performance 
Tape Storage Solution 
For Apple Users 


Ultimate File Security 

• 100% Data Restore and Interchange 

• Plug-and-Hay Connectivity 

Sharable Media 

• Multi-Gigabyte File Transport 

• Portable, Hot-Ruggable 


Technology 

Capacity 

in MBs 

Transfer Rate 
in MBfsec 

Price 

per MB 

VXA Tape 

33000 

3 

$0.03 

frnationTrarafi 

10000 

1 

$0.05 

DVD RAM 

9400 

27 

$0.05 

CD RW 

700 

1.9 

$0.50 

Zip 

250 

1.2 

$0.76 


Real Time Digital Video 

Cross-Platform Compatibility 

• Fire Wire/IEEE 1394/ilJnk Supported By 
All Major Manufacturers 


Call Exabyte sales at 1-800-774-7172 
or visit us on the web at www,exabyte.com 



Tape Storage By 

2 Exabyte 


® CofiifTHght 1Q02 Exabyte CorpwTitigin . Alt rights reserved, VXA andVXAope are registered indeinarks of Exabyte Corporation. 










sizeof (preferences), true); 

if C fGaaeBoardForu? ) 
delete fGameEoardForn: 

If ( fGanjelnfoFom ) 
delete fGaiielrjfeForiD: 

if ( fGame } 
delete fGaiic; 

1 

LLslntj* 3- Af>pSlof} 


Wlien the upplication receives ji stop event, AppStop saves 
Into ilie preference record the slate of tluii^rs as rectnxled in 
gGame, and deletes ilie objects tliat were created in AppStart. 


Supporting l^’orms 

Associated wiiii an active Fomt is a callback function llial 
processes events sent to the form. 'I'he classes CGameBoardForm 
and CGamelnfoForm handle events for the two types of forms. 
These classes are subclasses of LForm, 


Unirm :: [>Lspgitiii£vi:nl 

// $tztir 

Boolean Lt'oriii :: DispaicltKvent ( KveruType *lnRvcnt ) 

E 

// Identify dir uvcni type ^nd a'spijnd ui ii accordingJy 

Boolean handled ^ false; 

if ( rActI vel/Foritt ) 

switch ( EnRvent )eType ) 

( 

case fritiU pen Event : 

// ftilkw tip jificf o|X'n event 
FrmOrawForni ( FrmGetActiveFormO ): 
bandied * sA£:tiveLPorid->{>pent) i 
break; 

cane frmCloseKvPnt ; 

// Cliise litiilT btfoa- clo^^n^ if ntTcsisary 
handled ^ sActlveLFonn >Close(): 
break; 

case JnenuEvent : 

handled “ sActiveLForiii-> 

OaConniand ( inEvent ->data,sienu. iteitID. KlILL ); 
break; 

case ct1Sc1ectEvent: 

handled = sActiveLForn > 

UoSelecL ( InEvem >daia,ctISelecL-controlln* 

NULL ); 
break: 

default : 

handled “ false: 
break: 

I 

return handled: 

1 

f.isiniji 4. iJ*orm::I}is}taicb 


LRjrm :: 

// siaiic 

Boolean LForm :r Load t Ulnilb inFormlU ) 

// 

y/Jlic Pidm OS lias nx|ut'sictl tliai a fomi lx kiatScd. 

// If thf fonn can he loaded, nwii: the appropriate 

//IJkMTO 

I 

Boolean handled false: 

FomFtr forniFoiiuer = FrralnltForm [ inForialD ); 
if ( forinFolntsr J 

I 

sActlveLForm ” iDToLForin ( inFormID ); 
if f sActiveLFocia ) 


I 

FrmSetActiveForm ( formPointer ): 

FmiSeiiEventHandler { formPointer* kDlspatchEvent 3: 
handled ” true; 

J 

1 

return handled: 


Lisimg 5. Uvrm-lfMtd 


When the system function FrmGoloForm is called to switch 
fooTis* the applicantm sends llie function to liie class function, 
LForm:load. 'I’hat function finds the LForm object that will 
handle the form according to the If) rec|iiesied. li esta[)lishes the 
event handler for ihat class as ihe handler for f<jnn events. 

Wiien events arrive for a form, the class Function 
LForm:: Dispatch Event, sends the evenr to one of the virtual 
funciions, DoCommand, DoSeiect* Open or Close. SulKlasses 
need only t>verride these runctioiis. 

Game Board rorm 

This Ibnn displays the name of tlie current game, the 
playing suriace and Iwt) buUoas, One button clears the bf>ard. 
'fhe other switches u> the game information form. 

(X iujmfonn: lOjxn 

// viruia] 

Boolean CCameBoardFonii ;; Op^n (} 

[ 

// So up ;ill Lhc CStiu^nKladt^o objL‘L‘l^ 

FormPtr form = FrraGctActivcForm(]; 

IJTntlfi numberOfOhjpctf? = FtraGotHumhe?rOfObjects ( form ); 
fur ( UTfiilft j ^ 0: j i numhi'rOfOhjortn; j-H- ) 

t 

FormObjeetType * object Fol in or ' 

(FomiObjectType')FriiiCeH>bjectFtr( form* J ): 
FariBObjectKiTiid objeetKind - FrmCetObjeetType ( form, j ): 
if ( objeerKind ^ frmCadRetObf ] 

I 

For mCadget Type 'gadget 
(FormCadgotTy pr *) ob j oc t Po i ut or: 

CSquiireGadget ‘tsquaroGadgel *■ m-w CSiiimroGfidgor ( mTD, j* 
gadget * mCame ): 

I 

1 

Cam^KatieT y p e gain&Naiie: 
mGarao-)GntNatio ( gameName ) ; 

ScrFtf»idTexT ( CameBoar dCamnNiiiae Field * gacnoNanre 3; 

Ft miti nwFot m ( form ); 

//ARo in:ifk [licg;niK‘ ibui ihiH torm js 
mCamt/■ >SetForiii ( GameBoardForin }; 
return true: 

1 

Usfhm 6 . (Xre4nidi{>ijrdEorm::()fmt 

Open cr€fates a colleciitm or(il>jects to handle the gadgets 
that will be used in die Idnii. Tlie.se objects are not deleted in 
CGameBoardForm I'hey dek-ie rhemst‘lve.s a.s well .see in the 
sect if >n on gadgets. 

The list of controls in ihe luriii is scanned to Imd controls 
I hat are gadgets. As each gatlgel is founcL a LgameSquareGadgel 
object is created to handle its events. 

CXianidkranil^jrm:: [XiSclcct 

// vinual 

Booleiin CCame Board Form :: l)oSc?lccT ( Hint 15 InCotmnand, void 
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It's time for you to take a look at MGI 

MGI, a plug-in to 4D's award-winning server, WebSTAR, is 
designed to provide functionality to otherwise static web sites, 
whether for a private intranet or enterprise - class ISP/ASR 
MGI was specifically developed to be used by web graphic 
designers with no scripting or programming experience. If 
you know HTML, you know MGI. And if you are a 
programmer, you can learn MGI by the time your pizza is 
delivered. You can try out MGI for free - right now - without 
obiigation by downloading a fuliy - functioning demo at: 


http ://www. pag epia n ets oftwa re .com 


Searchable Databases 
Online Stores 
Info Baskets 
f G uestbooks 

' BannerAds 
Credit Card Transactions 

Counter! 
Password Protection 
Surveys 
; Quizzes 

■" Processing 

' ■Gdhditibnals ’ 
Math 

IhCiud^P^^ 

■■ pili':'i@itites:- .: 

Web Based ^aili 
(Mas#lid Ads 
Gfougs 

$Tifne;©alcuiatioM 
PGP' 

Token Jrickiitfg 
Galenidars' 
PifflM® RdpftH 
Send i® ■ 
B- Cirda 
GredftiBahk 


SOFTWARE BUILTWITH YOU IN MIND 


F=*aiO^F=‘l^n^t Ooftwar© lno_, 3252 Ootav*^ Straat, Flaleioht, MO S'T'eoo 


9.233.1 T-y^O 















*/*inRiram 7 ) 

I 

Boolean handled false; 
switch ( InCoinmand 1 
[ 

case GaneRoardClearEutton: 

DiCaffie-)ClearO i 

FonnPtr activeForm = FrraGctActivcForraOr 
FrtiiBtawFottii ( activeFonn ); 
handled true; 
break; 

case Gat&eBoardNewButtori; 
FrnGotoFornlGamelnfoForm): 
handled " true; 
break: 

I 

return handled; 


Listing 7. CGameform-Ofmi 


CfJia mcHoa rdForm:: Di >rr >mfi(tand 

DoSelect handles the two buttons: Clear and New. For ilie 
Clear button, if jusi tells the game object to clear its data and 
then redraws the form. FTmOrawForm will call the gadget 
handlers to do the drawing, llie gadget handlers will then 
retrieve any needed diUa from the game object as part tjf the 
redraw operation. 

GameInfoForm 

With this form tlic user enters a name for the game. When 
the user taps on the OK button, die current game is cle;ired anti 
a new game is started ami control is swiiched to the game Ixjual 
form. If the user taps Cancel, control also returns to tite game 
lx>ard form, but the name is not changed and the game resume.s. 

The user couid also switch to another application. In ihai 
cuse, the name field is restored as it was» wiili a name liiat the 
user lias cljanged. Imt mil confimied by tapping OK. 

// vinual 

Boolean CCaroelnfoForro :: OpenO 

I 

// lofiirm the gaim* that the info form ts active. 
nsCttmc >St!iForiB ( Cai»clnfoFor« ): 

Gan^KattteType tiasio: 

// II the lust open fomi wus u guitk* info fonn then use ihe tiame 

// tlot appeaml im Utui fumt. 

inGanie >GetUnconfirraedNaffie ( name ): 

// Orlicm isT U.SC tiu" name of tmrmnt gume 
if ( StrLen ( numc ) 0 ) 

mCatneOGetName ( name ); 

TuGaBe‘>SetUnconfirmedName { name }; 

SetFieidText { CameltifoNameFieidField, name ) ; 

FieldType “ GetField ( GameltifoNameFieldFieid ): 

FldDrawFioJd { field ): 

mOKWaaPressed = false: 
uaCancelWasFresseil ^ false: 
return true; 


Listing 8. CGctmelfifaform-Opcnt 

If the form was replaced because the u.ser changed 
applications, then an unconfirmed name is stored in the game 
(jbject and llie unconfirmed natnc will be loaded ittto the 
field. Otherwise, the name of the current game will be loaded 
into the field. 


C{ ramcInofForm: :Gosr 

// vittiiul 

Boolean CCamolnfoFons Closet) 
t 

GameNameType name; 

if C atCancelWasPressed J 

// Don't orc about what was in the field, 
mGano > S ntlfnco n f i rmcdNnrac ( “ : 

el so 
t 

if ( CetFieldText ( Catut^infohameFieldField, nsmo ) ] 
if ( mOKWasFressed ) 

I 

mGaiiie->Clear 0: 
niGarae-^SetName ( namo ): 
mGamn->SntlJncorLfirm0dNaine ("**); 

] 

else // switched upplica lii >ns 

tnCanie’>SetUnc{?nfiriiedNnisie [ iiuEme ): 

I 

// Return false to tell die OS to dean up the fonn 
// in die usual way after we have extracted titc ItiTu. 
return false; 


Listing 9 CGiimi^InfoForm , Close 

Close sets Uie name and tmconfimied name fields in the game 
according Co rw^o flags; mOKWasPressed and mCancelWasPressed. 


CCiumetnfoFomiiiOpt'n 

// viuuil 

Boolean CGatnelnfoPorm :: DoSelect ( 0Inti6 iuCotiintand, void 
TinFammV ) 

I 

Ikiolean handled = false; 
switch { jnCnmmand ) 

I 

case CamelnfoOKButton: 
mOKWasPressed ^ true; 

FrmGotofonntGameBoardForm): 

handled “ true; 

break: 

case GamelnfoCancelButton: 
nCatiCelWasProsScd ^ rrue: 

FrroGotoForlafGaincBoardForfti): 

handled = true: 

break; 

I 

return handled: 


Lisiitig 10 CGamehi/of(}rm::f.}oSelect 

DoSelect sets Uie appropriate flags according to which 
button was pressed. It then switches to the game board ftirm. 

A Gadget for a Square 

Instead of handling emits as is done fVtr forms, a gadgei 
callback handles commamh One type of tommand is an event 
eomtnand. So you need two levels of dispaicli: one at a higher- 
level for events, and one at a lower-level for commands. 

In 'ricTacFalm, there is a g:idget for each of the nine 
squares in ihe game Ixiard. The class LGadget handles the 
dispatch. Its sulxlass, CSquareGadget contains the code to 
respond to actions, 

'file Palm data type for gadgets contains a field for 
application defined data. IJnibrlunately, the argument passed to 
the handler is a pointer to an opa^itie structure. Palm 
docLimentation warns you not to directly access its fields. But 
they don't provide the accessor functions needed to conveniently 
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Scheduler and Contact Manger 
for the MacintoshI 


I ou 're a busy person. You Ve got things to do, 
I people to see, and a seemingly infinite list of 
I things to keep track of. Whether it's just yourself 
or a department at a Fortune-'^'500 company, 
you (and everyone that works with you) need to 
be organized. Maybe you've tried other ways: 
^ paper planners, lots of sticky notes, other 
^ software. But now you can't afford to waste 
B any more time or effort, you need a serious 
B solution. One that's so easy to use that you 
can get started right out of the box. One 
that will grow with you. One that has the 
features and capabilities you need. 

You need Now Up-to-Date & Contact! 

Try it FREE! Cet your free 30-day trial at 
http://www,poweronsoftware. com 


MyMicOSX 




Supports 
Mac OS 8.6 OS X 


POWER ON 
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the ;ipplinstton d;iia» making liic data Jield unusaldc. In Falin 
OS "1.0 an acce.s.sor funetion was added but it dt>esn'r work with 
all the commands that may be sent to the handler, 

llie workaround is to search all the gadgets l<Kjking fur a 
matching pointer. 

LGadget :: LGadj^et ( lflntl6 iuformlDp inCad get index* 

FoniC^dgfitType ‘inGadget ) 

: inFordjTD ( inFnrmTD )* mGad get Index ( inGad get Index )* 
mGedgeL ( inGsdgol ) 

I 

FomType *foniiPoiriter * FtmCetFormPtr { mFortnTD ): 
FrmSetGadgetHandier ( forraPointer, 
pGadgetlndex. SsClspatchGoiiiEiiand ): 
mPrevious “ sLast: 
fiLanr = this; 

1 

Listing 11. LCadget-LCml^et 


The amslructor stores a jxiinter to the data structure for tlie 
ibmi and sets a cla^ss function of LGadget to lx? the handier. 

// Matic 

Boolean LGadget ;; DispatchComaend C FoniGadgetType 
‘inGadget* 

arntlfi InCottOiand * void *lnParatii ) 

I 

Boolean suecesa ^ false; 

LGadget 'ICadgeL = Findl-Gadgct { inGadger ): 
auoceas = IGadget iGadget bDoComnuind ( InCoiiinipiid, 
inParam ): 

return succeas: 

1 

IMing 12. IXkidgcH-DisfmichChmmaml 

DispatehCommand is the class function tliat receives the 
command. It finds the LForm obfect to handle that comman<]. 

L( iadgr-t: 

Ikiolean LGadget ;; DoCoitmand ( UinLl& InConmatid* void 
^inParani ) 

I 

Boolean handled “ false: 
switch ( InCoronstTd } 
t 

rase forEaGadgerDrawCKid : 

Praw(): 

uiGddget >atU ♦visible = true: 

handled = true: 

break: 

case formGadgetHandieEventCind ■ 

handled ■ HandleEvent ( (BventType*)InParam ); 
break: 

case fdrmGadactDeleteCttd : 
delete ihl.^: 
handled true; 
break: 

case totmGadgetEraseCwl : 
handled “ false: 
break: 
default i 

handled “ Falne; 
break; 
t 

return handled: 

1 

U<tiNg IJ. lXladger::lk}Cbmwarid 


DoCommand determines the type of command and forwards 
it along. The dclcie {'ommiind gets sent immediiUely l>efore the 
enclosing fonii gets deleted. This handler deletes the LForm 
objea in respoase. 

irpadgcc :Ha]idlcEvent 

Boolean LGadget HandleKvent i RventTypo MoRvent ) 

I 

Boolean handled = false: 
switch ( inEv6nt->eType } 

I 

case frtuGad get Bn ter Event : 

//A pen down event has bc^n passetl to the fi>rm. 
handled = true; 

Tapped(J: 

break: 

case frraGadgetMiscEvent : 

//Tlic application, mil the system pcneralt-s 
// this event. Mot iLsed in the sample code, 

// ioclTKlc to allow lor hilun' modificatitins. 
bandied = false: 
break: 
default : 

// Should never get hert:. 
handled =■ false: 
break; 

1 

return handled: 

I 

lisliiig /.f fXjadget:Jkm£lki:ixmi 


CSt[uiireget 

For each of the squares in the game there is a gadget. Ff>r 
each gadget there is jn LSquareGadget object. Sqimres are 
numiiered 0 through 8. When ihe user la()s a game square, 
Tapped checks if ihc square is enipiy and tries to play an X at 
that location. It displays the current abject and then tells ihe 
LSquareGadget object corresponding lo the O response to 
dra\v itself. 

images of tlie X and O characters, and an empty field 
itnage, are stored as l>iimaps. Draw cxjpit.-s the appropriate 
bitmap lo the active fonii. 

(iSq u^ird'iadgrr. :Giqu;iR<iadgFt 

CSquareGadget CSquareGadget( Ulntlfr inFormlD* 

Ulnrl6 toGadg^l Index, FortuGad get Type “InGadget* CTlcTacCaije 
* InGame ) 

: LGadgei ( ItiFornin. inCadgetTndrx, InGadgeT } 

I 

ForroPtr form ^ FrmGetForraFtr £ IriFornilJJ }; 

UTntie objeetTD ■* FtmCorObjectld [ forra, ioGadget Index ): 
nsGatiJe " inGame: 

mSciuare = SquareNumbei: f objectIO J; 
sSquareGadger(mSquare] = this: 


Usting 14. CS(iUim<kuigL4::CS(ituiw€adgel 

Tlie cnn,siruclor uses the object ID of the gadget to 
dcHeniiine the numlx?r of llie .square, 'Hiat is the number that will 
lie used in the game logic to interpret the pl:iy. 


( LSqturtC iath^L iDraw 

// vinnal 

void CSquarcCadget llriiw () 

f 

Coord x: 

Coord y: 

FornType 'formPolnter = FrraGetForinPtr £ mFormlD ): 
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FrmCetObjecti'ositloti 

( formPointer, otGad get Index. &x. &y ): 
Lflntlb bitmapID = EmptySquareBlttiap: 
PlayerT contents = mGame->Get ( mSquare ); 
switch { contents } 

I 

c^jise kX t 

bitmap] D = XBiLntap; 
breek: 
case kO : 

bitraapID OBitmap: 
break: 

case kPlayerEiipty : 
dcfault; 

bliraapTh = Rn^pLySrjuarcBi tnap: 
break: 

I 

MemHandle resource ” DmGetResource 
C bitraapRsc. bitraapTD ): 

BittnapPtr hittitapResource = 

(Bi Tm/ipPT r)NfoTFiHanrf]eljOck f resource ); 
Err error = f)!nGoE;l,astRrrn : 
if ( ’error hiLJuapResource } 

[ 

WinDrawBltraap ( bimapResource, x, y J; 
error “ pfemHandtellnlock ( resource ): 
DmReleaseResource ( resource ]: 

1 

1 


LMin^ 15. CSqitiireCadgeL.Draw 


Tlie contenr of tJie square is determined from the game 
object. According to tlie content, select a resource with the X, O 
or blank bitmap. 


CiSq uarc< Ridjict: iTappcd 

// vErtLBil 

void CSquofcGadgct ;; Tapped () 
i 

UlntlS oResponse = kNoPositiori; 

if ( tnOame && iiiCaiiie->Cet ( mSquare ) = kPlayerEmpty ) 

I 

oResponse = □iGaj!ie->FiayX ( mSquare ): 

DrawO t 

if ( oResponse [“ kWoPosJtion } 

CSquareCadget *cSquareGadget =" 
sSquareGadget loResponse] : 
cSquereGadget->Draw(); 

I 

1 


LLsiin^ 16. CSquarc</ad^>et.:Td.ppe6 


When the user raps on a game s(|uare, this function 
responds by displaying an X, It gets live next O move from the 
game object and calls the draw function for the CSquareGadget 
for that square. 


Conclusion 

Developing for the Palm is easy to do with Code Warrior and 
POSE. Tlie Palm OS is continually evolving and making many 
housekeeping chores easier, such as improved bitmap supjxirt. 
Right now, the API reminds me of the early days of Macintosh. 
The application prognimmer must Ix^ concerned with a lot of 
messy details. I find that I miss liaving an application framework 
and feel the need to head in that direction. 

The need lo he able to fold up the teni whenever ihe user 
swatches applications adds an interesting twist to the job of 
programming for tlie Palm OS. Here, too, an application 
framework would come in handy. 


TicTacPalm is a fairly simple application. Additional features 
might include ilic ability to store and recall games, Ixam games 
between devices, and back games up to a desktop machine. Feel 
free to use the code presented here as the basis for writing an 
improved version of TicTacPalm, or possibly .some other game. 

RFFERF-NCES 

The Palm web ,stte contains tons of information ami links \o 
related sites. 

http://www.Palm OSxonn/dev/ 

■fo register a creator code just clic k on the list item Creator 
ID. As on Mac OS, creator IDs uniquely identify applications. 

The documentation in the Palm SDK is fairly good. There is 
a Reference manual and a Prognimmers' Guide. Some third-party 
books on l^alm programming are available. Pidm l^ogranimu{i^ 
by Neil Rhodes and Julie McKeelian is a good introduction, 
though the material in it is quite dared. 

Metrowerks has a demcj version of Code Warrior for Ihilin 
dial you can use U] get started, avaiiahle at; 

http://www.metrowerks.com/products/palm/demo 

There is a free online course in Palm progranuning offered 
by Metrowerks. It's at; 

http://www.codewarrioru.com/CodeWarriorU 

Credits 

'fhanks to Victoria Leonard for graphic resources. Thanks to 
Bob Ackerman and Victoria Leonard for reviewing the text. 
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By Gordon R. Meyer 


Apple Help & AppleScript Studio 


Providing Help Systems for 
AppleScript Studio-based Applications 

AFPLii HtLP AND Aqua 

AppleScript Slutlit) is an exciting prospect for Scripters - 
we iirv no longer limired to creniing the usiinl droplets or 
face less u Li lilies commonly dissociated with scripting 
hngoage development 

Rut power md opporttinify come ill n price. AppleScript 
Studio dcvck)pmenl also raises the liar” on expectations for 
how your application looks and behaves, like any oilier 
application on Mac OS X, tbllowing the Ac|ua Human Interface 
Csidelines will ensure your new application provides an 
excellent user expeiience. This article focuses on one aspect of 
A<tua - providing onscreen user assistance with Ap|>le Help. 

Virtually every application needs a help system, and using 
A[)ple Help is an easy and rundarnenial step in adopting Ac|ua. 
To get startetl all you need is a set of Hl'ML helf) files and this 
article. Aside from the time spent writing the hc4p comem, you 
can inifilemeni a working help systcMH in minutes. 

What is Apple Help? 

A[)[)lc provides the Help Viewer application for displaying 
your help content. 'ITie Help Viewer is optimized for providing 
onscreen help. It displays HT.ML 3 2, any QuickTime media you 
care It) use, and it can run AppleScript automations to assist 
Li.sers in accoiuplisliing complex or common tasks. (Rccause 
AppteNcript Siudio-iiased applications are already .scriptahle by 
default, there is a lot of opportunity tti enhance your help with 
iiselul automations. Something to consider after you've gotten 
your hist-cul at Help impletiiented/) 

The Help Viewer also provides a built-in search engine that 
quickly gives relevancy ranked search results for your help, and 
all the help installed on the users eompuier. Slionly, yoLt'li learn 
liow to ensure youi help content is searcliahle. 

Witen y(Hir applicuiion adopts Apple Help, it will be 
automatically listed in the Help Center. The ffelp Center allow.s 
users to view and search an applicatioiTs hel[) without liaving to 


open the application. ICs a great way to find out which 
applications can handle a special task that you have in mind. 

There are more Apple Help features sudi as aiitomaliealiy 
building “table of contents” files or the ability to mix locally- 
stored and Inrernet-based conient. For information about them, 
.see ProncHng Ifser Assisiance unlh Appk' Help. If yt)ti prefer to 
watch and listen Instead of reading, tlie WWDC 2001 streaming 
video of the Apple Help session also introduces all the features 
and capabilities. 

What type of infoniiaiion should you include in your help? 
Making good onscreen help is a whole article by itself, but the 
“HelfV' ( hapier in Aepm Hiunan Interface Gukklitm has stime 
discussion, as does the WWDC 2001 session. If you would like 
some guidance consider using these resources. 

For ihe purposes of this article, don't worry alioul all the 
bells and whistles, just gel ytRir conient into HTML 3,2 formal. 
You can repurpose existing Rles from your Web site, or use 
whatever HTML auihoring tool you normally use and aeate the 
helf) from scratdi. 

Pretaking Your Help Files 

After yovi've written your help, you need to make one 
minor addition to identify the “siari page" (or “home page) 
for your help book ;ind prewide the title of your help system 
for the Help Center. 

You do boih by adding one META lag lo the start page 
for your hook. 1'his is typically the table of contents page, or 
the spla.sh page, or whatever psige you waiii users to see 
when the Helf) Viewer opens. If youhe re using eonienl from 
your Web site, it might be the index.html file, for example. 

Listing 1: AppkTitle example 

<btra1> 

<head> 

<tiieta name='’AppleTitie" CDntent-”MyAppNatiie Help") 

</head) 

<body> 

</faady> 

</html) 


(k>rdon Meyer (gi)rtl<)ri@:ij>p]c.cuiid works on Apple Help and related instructional products. 
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We're Easier. 


Create anything from prototypes to full professional applications. Just drag and drop interface 
elements while REALbasic handles the details. You concentrate on what makes your stuff great — 
your ideas! REALbasic compiles native applications for Macintosh, Mac OS X and Windows 
without platform-specific adjustments. It's the powerful, easy-to-use tool for creating your own 
software. Each version of your software looks and works just as it should in each environment. 

Complex problems shouldn’t require complex solutions. The answer is REALbasic. 


3 REALbasic 


Download a free demo, www.realbasic.com 











The content of the AppieTitle tag is the name of your help 
book. This Ls (he name that gets listed in the Help Center, and 
it’s ht)w Apple Help idenlifies wliieh iKK^k to open from your 
application's help menu. The Aqua HI Guidelines recommend 
that you use the form *'MyAppName //e//T. 

Making your help searchable 

The search engine in Help Viewer is fast. It can search 
hundreds of pages of help in ju.st seconds, returning a list of 
the most relevant topics in your help b(Jok, To accomplisii 
this it uses a pre-genera ted index file. To make your help 
searchable, which is strongly recommended for the best user 
experience, you use the Apple Help Indexing T<kiL Please 
don't forget this important step, users get frustrated if they 
can't Ifxrate information by .searching. (Indexing is also 
required if you’re using some of the advanced features, such 
as Anchor Lookup, as described in the Apple Help 
documentation.) 

The Apple Help Indexing Tool is installed in 
/Developer/AppHcatioris/. To use it, simply drofj your folder 
of help files onto the tool. The Indexing Tools quickly scans 
all the pages and creates ihe search index file in the correct 
location. 


@00 p Applications 
Apple Help indexing Debu 



SuffVV' ler Help fw 

'S'- 




4 ► 


iirag-ami-drop to etuthie searching 


That's all there is to it. You can gel fancier If you d like, 
by adding keywords or changing the way some topics are 
indexed, but for most uses all you have to do is use the default 
Indexing Tools setling.s and drag-and-drop your help folder. 


with Mac OS X's multi-lingual support it permits you to have 
localized help along with the application itself. 

Select the Resources folder in Project Builder, and then 
choose Add Files from the Project menu. Select the main 
folder of your help content and turn on tlic option to create 
folder references, and then click the Add button. 


0 Recursively create groups for any added folders 
@ Create Folder References for any added folders 


Select this option ivhen importing your help folder, 
Your help folder is now listed in the Resources list. 


© Groups & Fites | 

fl 

▼l^SurifWrtter 

. 

iii 

Scripts 

' 1 

1 j 


Resources 


;i!^ 

& ^^MainMenu.nib 

i 

■: i 

1 1 

& ► OlI InfoPlist.strings 

i 

i 


0 AppleScriptKFt.asdjictionar 

i 
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► 1 ^ SurfWriter He Ip 



^ ^ Other Sources 



i^tPI Frameworks 


1 - 

1 iijr 


Help files added to a project. 


Add Help to the Property List 

Choose Fdii Active Target from the Project menu. Ihen 
click the Application Settings lab to display the settings for 
your build. 

In the Basic Information section, specify a bundle 
identifier. See inside Mac OS X: System Overmew for more 
detail, but in brief you specify a unique identifier for your 
application using Java-style naming, 

f Basic Informalton 


Add Your Hfj p to Yode Project 

By adding Uie MRTA tag and creating a .search index you 
have finished everything you need to do lo your help 
content, Next, you add the help files to your application's 
package and tell Cocoa you have a help system. 


Executable; ! SurftVnter 
Idemifier: fc^.MyCreatCompafiy-SyrfWriter 

Enter a hundie idenlifier 


Importing into Project Builder 

In Mac OS X help files are stored in an application's 
bundle. This keeps everything tidy - help always travels with 
the application when it’s installed or moved on di.sk - and 


Click the Hxpeit button in the top right corner of the settings 
pane. Tins allows you to edit die Propc'rty List directly. 

Click the New Sibling button, then edit the new entry so 
the key is CFBundleHelpBookName and the value is a string 
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that matches the contents of the AppleTitle tag that you put 
in your 

Add another new sibling called CFBundleHelpBookFolder 
with the value being the name of your help folder that you 
previously imponed. In our example both key values are the 
same because the folder where we store our help files is named 
the same as our book. That's not a requirement, but it is 
conventional. 


f fim ^ •'_ Orntii 


ProfwrtyLfst 

•'disic 

Value 

C FSundk De velopme ntite g ion 

String 

t English 

CFSundleE^ ecutable 

String 

t SlirfWriter 

CFBund leGetl nfoString 

Sifing 

: 1.0 

Cf iund \t Hei pBookF a Id er 

Strmg 

; SurfWntcrUdp 

^ CFBundleHdpBoQkfJame 

String 

^ SurfWriEer Help 

Specifying the help hook and folder 

names 


Edit The Help Menu 

Yoirre in the home stretch now. The last task is to 
rename the default Help menu that is automatically created 
for your application. You don’t have to do anything to make 
the menu work; Cocoa provides the functionality 
automatically bec:aiisc of the changes you made to your 
property list. 

In Project Buikler, double-click your interface definition 
file (MainMemi.nib, unless you've changed it) to t)pen it in 
Interlace Builder. 

In the menu layout, change the Help item to march the 
name of your help book. The Atjua guidelines recommend 
the form MyAf)pIVa?ne Help"'. Note that you automatically get 
the correct keyboard shortcut, courtesy of Cocoa. 


0 Q MatnM^nu.nib - MainMenu 
Application File Edit Window 





Edit the Help menu item. 

ThaPs it, youVe done! Build your app and try it out. 
When you select your new Help menu the Help Viewer will 
bunch and open to your book. If it doesn't work make sure 
dial tlie property lisi values maicli up with the appropriate 
AppleTitle and help folder names. Also check that you 
remembered to enter a bundle identifier for your application. 

Your AppleScript Siudio-bascd application is now one 
step closer to providing a great Aqua user experience and 
useful help for your customers. And, along die way, you've 
learned ht)w to implement a help system for any Cocoa 
application. 
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Felt Tip Software presents 

Sound kudio 2.0 


Built for Mac OS X 

With Sound Studio 2.0, you can: 

Digitize cassette tapes and vinyl records to make CDs 
Record live performances and interviews 
Record your favorite radio programs with Timer Recording 
Edit out dead air, glitches, and mistakes in recording 
Apply any of 19 effects induding Reverb and Chorus 
Create new sounds and loops 

S(mnd Studiti ia an audio recordinj' and ediUng applicalion built for 
Mac OS X. It can also run on Mac OS versiona 8.1 and up. Stjme 
systems may need a USB audio input device to record. 

Only $49.99 
Download 14-day trial version at 

http://www.felttip.com/ss/ 

felt tip software 

807 Keely Place, Philadelphia, PA 19128, USA 
www.felttip.com 
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NETWORKING 


Building a LAN 


Conceptually^ building a ]AN is very simple. Connect all 
your computers lo a hub or swiLcli, and then connect your 
internet connection to the same hul^/switch. Everything works 
from there, and everybody is happy, d his approach will work 
just fine for a low-trafhc network with relath^ely few nodes, but 
as things begin to grow (and if all goes well they will grow) this 
approach can cause problems. It is best to introduce some 
sinictiire to your IAN early in its life, so that growing is as pain- 
free as possible, 

'Ibere are a few things that you should study before 
de.signing and building your IAN: 

• 'I'he difference between iialf duplex and full duplex 

• Basic information on the inner workings of Ethernet 

• The difference lx:iwecn a hub and a switch 

■ Basic information ai>aul oilier layer 2 networks you wall he 
using (802.11 wireless^ for example). 

We will cover llic.sc Lssucs below. 

Half DifPiJ^x vs* Finj. Diipi^x 

A iialf duplex network is one where only one node may 
transmit at a given time. Standard ethemet networks have this 
property. The IEEE spec was updated to allow' for full duplex 
operation, which means nt>des may both transmit and receive at 
the same time, There is a restriction on this, which is that a full 
duplex segment may only have two nodes on it, or where the 
full du[)lex node.s are all connecied to a sw itch. 

How Ethernet works* 

Ethernet i.s a layer 2, (originally) only half-duplex CSMA- 
CD iietw^ork technology. Layer 2 describes wliere it falls in 
the OSI protocol stack (See the OSl Network Model sidebar). 
C’SMA-ClJ means: 

€S: Carrier Sense, This means that before sending any 
traffic on tlie netw^ork, any Hrherner node must listen on the 
netwwk to sense if any traffic is already being transmit ted. If ii 
i,s* then the node must wait to send its traffic. 


MA: Multi Access, An Ethernet network can have multiple 
nodes connected to it ai the same time. 

CD: Collision Oetectiori. Due to the fact that netw^ork 
transmissions do not move across the network in.stamly, bttt with 
some latency it is possible that two nodes on a network miglii 
both detect at the same time that no traffic is being transmitted 
on the network, and ilius .start transmitting at the same time. 
When this happens, a collision is generated, wdiich every node 
on the network hears. The nodes then use a random exi>onential 
!>ackolT algoritlvm which defines how^ long the ncKie must wait 
i>efore transmitting again. 

A collLsion can only occur while the ethernet header 
(preamble) is being traiTsmitted. For Fast Ethernet this is acruaily 
the limiting factor in the length of a segment (this et)mes out lo 
about 100 meters). For regular 10 Mbps ethernet the lengtli of 
an ethernet segment Is constrained by signal strength ( this comes 
out to about 150 meters). 

A collision domain is defined as a netw'ork that can only 
have one node transmitting at a time (or else a collLsion occurs). 

Now\ dejtending on what sort of a t'ore your ethernet 
network is composed of you may have just one collision domain, 
or you may have several. There are two types of devices that can 
serve this role, hubs and .switches. Hubs are far !es,s expensive 
tlian switches (although as is always the c'ase with compulcr 
equipment those prices are dropping). When a hub receives an 
eihernet frame on an interface, it indiscriminaiely forwards sak! 
frame to all of its ports. A hub has no know ledge of which devices 
are connected to its ports, so it relies on the device itself to decide 
whicli iraffic Ls iis own. This means ihai eve 17 port on the hub is 
a jxirt of the same collision domain. A sw'iuTi is essentially a more 
intelligent hub. Switches have knowledge about whicli MAC 
addresses are <x>nnected lo which switch port, 'Ihiis, unicast 
frames are only forwarded lo the port that has the destination host 
on it ( broadcast packets are still foivvaided to all of tlie switch 
ports). In a swatch, each port represents a different collision 
domain. This means that multiple ncxles connected to a switc'h 


Alec Peterson is tlie Chief Te<‘hnt>ltigy Officer for Catbird Networks {http://www.calbird.com). Catbird provides performance and integrity services 
to businesses fliai have public-facing infrastructure and want to ensure that iheir Internel presence is alway.s available and not defaced. Alec has 
extensive cxptTience building and operating large networks, and is actively involved in Internet address allocation fxjlicy. He is currently chair of tire 
American liegi.stry for Internet Nimiber.s Advisory Council. 
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Awesome! 


"The power, quality and feature set of 
Lasso Pnofessional S fs very impressive. 
The new documentation is definitely 
among the best in the business.*' 

Johan Halmstad, Sweden 


"3iuro World has managed to add an 
immei>&e amount of functionality and 
scalability without sacrifidrig any of the 
ease-of ‘Use of previous versions. New 
features like LassoApps, custom tags 
and Lasso Script create a development 
environment that seems almost limitless.'* 

Tom Wiebe; Vancouver Canada 
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Out^ BJdPowflfi^ 




“With Lasso^ I have beerr able to single- 
handedly develop sophisticated solutions 
for internal and e;»(ternaE use in less time 
than I see teanr^s of people take with 
other middleware languages." 

Greg Wtifits; Santa Ana, Ca/ifomia 


"This new release. I have got to admit, 
is truly amazing. The rich array of new 
features, the brand new documentation 
and the amazing new administration 
interface make Lasso Prafessional 5 
definitely worthy of a purchase." 

Bhan O/sen; flmoJflyn, New Vbrk 


Upgrade today to the most powerful Web application server for 
Macintosh and beyond and you'll discover why so many Web 
developers claim Lasso Professional 5 is the must-have tool for 
quickly building and serving powerful data-driven Web sites. 

Lasso Professional 5 introduces a next-generation, object-oriented 
Web programming language, advanced Web application server 
administration^ an embedded Lasso MySQL^*^ high-performance 
database server, a new distributed architecture, new platform and 
data source support, unprecedented extensibility and customiza¬ 
tion, 1800 pages of rewritten documentation and over 200 new 
features and enhancements. Lasso Professional S provides vast new 
power and features while maintaining the legendary ease-of-use, 
performance, atid reliability that make Lasso the preferred tool for 
tens of thousands of Web developers, ISPs, and IT/IS professionals. 



Lasso Administration controls your entire setup via an 
attractive and intuitive Web browser Irtterface. 



If you're serious about building and serving data-driven Web sites, 
but don't want to spend a serious amount of time getting it all to 
wori<. there's no better choice than Lasso Professional 5. 

Visit the Blue World Web site today and see how Lasso products can 
help you quickly build and serve powerful data-driven Web sites. 

Lasso - The Leading Web Tools for Macintosh and Beyond 



Lasso Database Browser provides instant access to all 
your databases, without writing a line of code. 


blueworld 

www.blueworld.com 


O 2001 Btu* Warld CartimiininttHnim. Im;. n n tmdnnvirk iit MySQL AB. RfeMilkar Pra m irad^rruirli at FrieMakor. triC. Ussfi. LfttfoApp. Ul«oStnf?t 

arid Blu? World Arv ErsciertUrlc! of l^lue World CotnrTiiLriicatiDRs,. Itk. AH lights rttHorvad. 























can be LmnHmilttng at the same lime. However^ if a switch port is 
operating in half-duplex mode, then tlic switch cannot iraasmii on 
a given port at the same time a,s another node on that same port. 
Note that you can connect multiple ntxies to a single switch pen 
by connecting a liul> (or another switch) to a switch f>on, and you 
c'an also ca.scade switches fie, connect s^^atches to switches). 

Collisions are a normal pait of operation on a half-duplex 
etlicmel netw'ork. However, the int)rc active nodes yt>u have on 
a network the more collisions you will have. Too many collisions 
can seriously degrade network perfomiance. Based on liiis 
statement one iniglii ask how many collisions is too many'. The 
best way to see if collisions are causing a f^jroblem is to ping 
across the network (ie, ping one host on tlie netwTirk from 
an<idler one). Latency across the Fthernet should lypiailly be 
only a couple of niiliiseconds, and packer lass should be 0. If 
either of tliese is not the case, then you probably liave im many 
players on ihe network, and .something should lx* done 

Troubleshooting tip: When a network is setup incorrectly, 
you may notice the late collision’ counler incrementing on one or 
more of your ethernet devices, in a nutshell, this means that a 
collision t>ccurred after the preajnfilc of ihe cthernet fnime. The 
most common cause of this is when you liave one end of an 
ethernet connection running in half duplex intxle, and the other 
end mnning in full duplex mode. In thi.s case you will notice the 
late collision counter incrementing on ihe half duplex side, 
becau.se the other side of the cf>nnection (which is full duplex) is 
expecting to be allowed lo transmit and receive at the same time, 
hence it is ignoring collisions. A fcs,s common cause is when you 
have an ethernet network that is too lung, bite collisions ]ia[)[5en 
in this case because tlie l>eginning of the preaJiible has not 
reached the end of the network lx;fore ihe tran.smiiiing node ha.s 
completed sending il, thus the transmitting node assumes that it is 
allowed to transmit the entire frame. 

If your entire network is Irtiilt using a .single hub (or a 
series of hubs) then your first step should be lo upgrade to a 
switch. 'I'his will reduce the number of devices on the same 
colli.sion domain (by putting each node on its own collision 
domain). This in turn increases the number of nodes that can 
transmit at the .same time (from 1 lo n, w'here n is the number 
of active switc h ports). Once you have a swatch at the center 
of your network fabric you should not encounter many 
problems until you begin to run low on network pons. You 
can address this by either hanging hubs off of ,switch ports, 
or by stacking switches together. Many switches have their 
own proprietary trunking system for conneding i lie in 
together. Others have gigabit ethernet ports for lit is [>urpo,se. 
Either method will work just fine. 

Switches come in a variety of shapes and sixes. For 
example, you can get a managed switch, which allows you lo 
hardwire ports to a specific duplex/speeci setting among 
other things. Or you can get an unmanaged switch which 
theoretically takes care of this for you. If you want to run any 
full-duplex devices on your network the author strongly 
recommends gening a managed switch and hard-coding all 
ports that need to be full duplex u> that setting. The protocol 


for auro-negotiating duplex very seldom works properly, even 
between devices that are made by the same vendor. 

Other Iayek 2 protocols 

IEEE 802.11 is probably the most common non-ethernet 
LAN protocol being used today. Sometimes called wireless 
ethernet, IEEE 802.11 describes protocols that allow 
computers to communicate without physical wires between 
them. This protocol is a CSMA-CA protocol. You already 
know what the CSMA initials stand for. CA in.siead of CD 
means Collision avoidance' instead of ‘collision detectionL 
This means that on an 802.11 network collisions do not exist, 
lastead, the radios negotiate amongst themselves to decide 
who can speak at any given time. 


OSI Network Stack 

Network pixjitx’oLs are huili on top of one another lliis is 
done using die QSl Network Model. Note that Internet Pn>t(xx>ls 
am not designed by OSI, but ratlier by the IITLR Thus, some of 
the OSI layers are not cleanly represented by Internet Praoa>ls, 
Tlie layers are as follows: 

Application layer: The application layer provides 
autlientication and data syntax. Everything at this layer Ls 
application specific. IfflT is a w^eU known application layer 
prx>T(.x:oi 

Presentation layen Hie pre.senLtiion layer pitwides 
nianipulatioii of application layer data, the mast common way is 
through enciyption. SSL is a presentation layer protocoL 

Session layen The session layer establishes, manages and 
tenninates connections lx;lween applications. 

Transport layer: The tnin.spoit layer provides transfrarent 
data transfer Ix^tween hosts. 'Ibis layer is responsible for 
ensuring packet delivery and veracity as well as flow contml 
Tlie combination of DNS and ICP or I.IDP perfonn die junctions 
of the session layer and the transpe^rt layer. 

Network layer: The network layer is responsible for 
routing and switcliing packets between nodes on the network. 
IP is a network layer protocol 

J>ata Link layen The ckita link layer is responsible for 
assembling bits Lransmitted on a network into chunks of data, 
known as fi'ames. Etliemet is a data link layer protocol. 

Physical layen The physical layer is resporLsible for 
representing electrical (or other) impulses as bits (1 or 0). 
Basically any physical media lliat has data transmittcxl over it is 
part of die physical layer. 

The end result of diis layering system is Llial higher level 
protocols do not need to liave any knowledge of the structure or 
makeup of the underlying network, 'I'his is what allows the 
tntemet to run over many different physic'al media (fiber optics, 
copper wii'es and air waves), When a web l^rowser makes a 
connection to a web server, it has no idea how its traffic is routed, 
just that it got them. 
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802.11 relies on something referred to as an 'access point' 
for nodes to talk to one another as well a.s other networks (such 
as a physical ethernet network). The acce.ss point lias \wo 
primary^ responsil >ilitics: 

1) Allow wireless nodes to talk to t)ne another by acting as a 
central huh fc3r all of the radios to register with, 

2) Allow wireless nodes to connect to other types of layer 2 
networks by acting as a bridge. 

All traffic on a wireless network will go through an 
access ptjint, regardless of whether it is destined for a 
terreslTial network or for another radio cm the same wcireless 
netw(mk. This isn’t nmeh of a problem since the wireless 
netwwk is a single half-duplex segment anyw^ay. 

Scaling wirele.ss networks has to take into account your 
goals. Scalability is accomplished by distributing muki[)le 
access points in an intelligent manner, based on your goals. 
You can use multiple access points in a given area because 
of ilie fact that 802.11 defines 13 channels iluil can all be 
used simultaneously on top of each other. If you intend to 
have a large number of radios in a .sina 11 physical area, then 
you would w^nnt to have multiple access points in ilia I same 
area, run [ling on different channels. Should you need more 
than 13 access points, you can reuse channels as long as any 
two access points rttnning on the .same channel are not 
wdtliin range of each other. Access points distributed in this 
manner are typically all given their ow'n ethernet connection 
to the IAN. It is possible using certain access points to have 
some radios act as repeaters (cisco/Aironct are known to the 
author to support this). This technique should only hi: used 
as a last resort to get sSonie extra coverage, since it requires 
that the repeater radio run on the same channel as the one it 
connects to on tlic ethernet, thus it does not give you more 
wireless bandwidth. 

Troubleshooting tip: If you are experiencing poor 
performance on your wireless network, do not automatically 
assume that the problem lies in the congestion of the 
wireless network itself. Remember that the access point i.s 
comniuniaUing itsing CSMA-CD i[) the ethernet network. So 
if it is receiving traffic from the ethernet and wireless 
networks at the same rime, it needs to buffer data before it 
can i)e transmitted. S<ime access points only have ifie ability 
to speak half-duplex over their ethernet ports, and since they 
act as bridges they have implemented a very aggressive 
collision backoff algorithm (which means they give up trying 
to send a packet over the ethernet a lot more quickly than 
some other ethernet devices would). If you have this 
problem investigate wdiether you can get your access point 
to support full-duplex ethernet. Should that not w'Ork then 
you will want to distribute more access points on different 
channels to cover the same physical area. 


However, if your scaling goals involve covering wide 
phy.sical areas with relatively few wireless mjdes, then you 
should U)ok into getting a high gain omnidirectional antenna 
for your access point. This will significantly increase the 
range that a single access point can ctsver. 

Since 8()2d 1 lias become so popular recemly, tliere are now 
many vendors selling access points for over a large price range. 
The products that are billed a.s residential products can certainly 
be used in a c'ommerdal environment, h<iwevcT you do get w hat 
you pay for. Read the Fine print w^hen purchasing such device.s, 
as .some of them have a very low limit on the number of radios 
that may be connected to the access point at a given time. The 
best advice is to evaluate your needs and then make sure you 
know' everything you need to know about a prcxiucl Ix^fore 
purchasing ii. Note that should you want to setup a rcpcraler 
radio somewhere in your network you will probably need to 
purchase a higlt-end access point for both the repealer radio as 
w'ell as the one connected to the physical network. 

ft is also possible to use 802.11 for point to point 
isriclging, by using directional antennas. Mowever, such 
implementations are beyond the scope c^f this anicle. 

CONCtUSION 

As with most things in life, LANs gel more complicated 
the larger they gel. If you have a .specific netwuirk design in 
mind w hen getting started on your LAN it w ill make growing 
it a much less painful task 
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MAC OS X 


By Rich Morin 


The BSD Man Pages 


How to find them; how to read them. 


Welcome 

^'SL'ciiun 7”, the name of this column, is also ihc 
shorthand term for ihe "Miscellaneous Inrorinutitm” 
section cif tile Berkeley Software Disirihutitm's manual 
pastes (knciwii in their friends as the BSD “man pa^^es*'). 
This column will feature miscellaneous information on 
HSD-relaied aspects ni Mac OS X, including ;ip]>licaiion 
design, documentation, and even tlie polilics of the 
developer and user communities. 

Mac OS X is the most widely'disseminated version of 
BSD, I ml many Mac developers are a liit unclear on what 
BSD actuatly is. So, a word of explanation may he in 
order, liSI) is a well respected operating system, wiifi a 
tong history of solid engineering. Derived from Ihiix 32V, 
I5Sl> is used for network servers, fireualls, and many 
other mission-critical applications. 

Darwin (and ilierehy Mac OS X) is Irased on the 
FreeliSD and Net BSD distriliulions. As a result, it can take 
advantage of a welhdeveluped operating .system 
environment and thousands of “porletD applications from 
the FreeBSD Forts Col lection. Clearly, BSl>'s solid 
technology and adive devekiper community tnake a 
poweitul contribution to the Mac OS X story. 

GEri'lNG Staried 

BSD (and other Open Source) developers maintain 
several thousand "man pages” (manual pages), covering a 
wide range of topics. Because the pages are written by 
developers, they tend to be atithf)ritative, consistently 
organized, curreni, detailed, and refresiungly honest. On 
the other hand, they also tend to be terse, tightly focused, 
and a bit unjiolished in spots. 

Consecjuenily. reading man pages may not bt* the best 
way to approach a new and complex topic (e.g., NFS, 
socket programming), hut it is an extremely handy way to 
learn ahntit specific commands, remind yourself about 
ft)rgoilen details, etc. Once you've read a few man images, 


I predict that you 11 get addicted to their strong points; you 
may even (eventually) forgive their deficiencies. 

Altht>ugh it isn't critically necessary, you1l find it 
useful (and fun!) to have some Terminal windows on 
hand while you read this article. For one thing, you1l he 
able to see the actual output of the commands I’m 
tiescrihing; for antnher, you'll be able to try things out. 

Using the Finder, navigate through the Applications 
and Utilities folders. When you finrl the kon for the 
lerminal Utility, drag it into Uic Dot'k. Now, double-click 
the icon twice, creating two Terminal windows. Unlike 
typical applications, these window's are not closely tied to 
each other. In fact, each 'rerminal window' prt>vides an 
independen! BSD "session”. 

You should proliably spend a few seconds arranging 
the windo\v.s, so that you can see rliem lioth at the same 
lime. Also, .siretch at least one of them vertically (keeping 
die widtli constant). This w^ill let you see more of your 
commands’ output without scrolling. 

To view a pariicular man page, you must ask the 
system to run the "man” command, giving it the name of 
the page you want to see. We can try this out by asking 
for the man page that describes the “null” device: 

[localhostr^l rdwX roan mill 

NLlLLtA) System PT«>gr3mracr'fi Kanunl N11LL(4) 

mm 

null the imlJ device 
DESCKimoN 

The null device accepts t*ud reads da La as any ordinary 

(and willin^J tile ■ but throws it away. The length of 

the null device is always zero, 

FILES 

/dev/null 
HISTORY 

A null device appeared in Version I AT&T UNIX. 

Headings 

As the example shows, each pan of the man page is 
introduced by a descriptive heading. Some headings (e.g.. 


Rich Morin has lx*cn using conipuEors since 1970, Unix since 19H3, and Mac lya.sed Unix since 19SS (when lie fielped Apple creaie AylJX 1.0). When 
he isn't writing ibis nduiiiir Hicli runs Prime Time Freeware (w ww.pif.coni), a publisher of Ixxiks and Cl) ItOM.s for the Free and Open Source software 
coni mil nity. heel free to write to Rich at rdm^^ptf.coiii, 
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NAME, DESCRIPTION) will show up on evc?ry man pagei 
others (e.g., FILES, HISTORY) only appear when needed. 
Some, finally, arc invcnled by the page’s author. Here are 
some a)mmQn heading.s, in the order they would 
normally appear on a man page: 

• NAME The following text gives the nameCs) of the 
described iteiTi(s), followed by a terse description. In 
the case of commands, only one name will typically be 
given. In the case of library functions, however, there 
may he a long list of entry points. 

• SYNOPSIS The following text gives a (stylized) 
description of the nt)rmal usage tnode for Ute itcm(s). 
In the case of commands, this will siiow the possible 
option flags; in the case of system calls and library 
functions, it will s1k)w representative declarations, etc. 

• DESCRIPTION The following text gives an extended 
description of the item(s), including options, usage 
considerations, etc. Some descriptions go an at great 
length. 

• RETURN VALUES The following text descril>es the 
return values for the itemts). 

• ERRORS The following text lists pi)ssiblc error 
conditions and resulting actions. 

• FILES The following text li.st.s related files. 

• SEE ALSO 11 le following text lists related man pages. 

• STANDARDS The following text lists ap[>licabte 
standards, sometimes discussing the degree to which 
the described iiemt,s) comply, 

• BUGS The following text lists ways in which llie 
command fails lo meet the documentor’s expectations. 
Some vendors find this section embarassing, so they 
rename or remove it. Feh! 

• NOTES The following text lists ancillary information 
which is not appropriate to any of the other sections. 

• HISTORY Tlie foll«>wing text tells where (i.e., in which 
BSD OT Unix variant) the item first appeared, etc. 

PACiiNO 

With all of this detail, some man pages can (and do 
:) go on for quite a while. In fact, multiple-page “man 
page.s” are ciuiie common. .So, the man command is set up 
to let the reader “page” tlirough the text. The default 
“pager” on Mac OS X is “more”; for a rundown on its 
capabilities, look al its man page! 

[locallios t;rdmX man more 

Although more isn’t very sophisticated, it does 
respond to the space bar (skip to the next page), the 
return key (move forward one line), “q’’ (quit), and a few 
other commands. If you want more featiire.s, try the GNU 
Project's “less” command (less is more, more or less): 

[1 oca 1 hoist rdmX aetenv PAGER les^ 
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Sections 

The man pages cover a wide range of topics: 
administrative and user commands, C language interfaces, 
devices, eie. Tf all of ihc topics were simply sorted logeilicT, 
tiiere would be name clashes. For instance, there is a 
passwd file, as well as a passwd command. To keep things 
straiglu, the man pages are divided into nine sections: 

• Section I (General Commands), I'hese are commands 
that any user luiglii enier from ilie command line or 
use in a “shell scripC. Some example commands 
include cd, Is, and rm. 

• Section 2 (System Calls). These are C language 
interfaces to kern el-provided services. Note that a 
system call, by definition, causes a context switch into 
tlie kerncL The application is halted until the system 
call completes. Some example system calls include 
close and open. 

• Section 3 (Library Functions), These are also C 
language interfaces, but the function runs (in general) 
with the application’s context. Of cour.se, .some library 
functions make system calls, which do context 
switches, as de.scribed above. Some example library 
functions mclude fopen, scant, and sqrt. 

• Section 4 (Devices and Device Drivers), 'fhese are the 
externa! interfaces to sy.srem devices. So me devices 
(e.g., /dev/nufi, /dev/tty) are intended lor direct 
(command-line) use; others are only accessed by 
application or system-level code. Consequently, the 
descriptions in this setaion vary con.siderably in level 
and coverage. 

• Section 3 (File Formats). Many BSD activities are 
controlled or monitored by means of files. Tljis section 
describes some of the critical files that an administrator 
might need to read or edit. Note, however, that Mac OS 
X LLses different admini.sirative iiiechanLsm.s than mt>st 
other BSD variants, so your mileage will definitely vary! 

• Section 6 (Games). Some BSD distributions include 
recreational programs; others do not. By placing these 
programs in a special area, the operating system eases 
monirf)i-ing and control of I heir use. 

• Section 7 (Miscellaneous Information). This section 
includes descriptions that are nor tied to any given 
command, file, or function. Look here for liighdevel 
introductions, etc. 


• Section 8 (System Maintenance and Operation 
Commands). These are commands that the system 
administrator might enter from the command line or 
use in a “shell script". Some example commands 
include chown, fsck, and tunefs. 

• Section 9 (System Kernel Interfaces). These are C 
language interfaces to kernehprovided services. 'I'hey 
differ from system calls in that they can only be called 
from inside the kernel. Thus, they arc only of interest 
to kernel programmers. Mac OS X does not currently 
have this section, but FreeBSD does, so J expect it to 
sliow up eveniually. 

Navigation 

Going hack to the case of pas.swd, we see that the 
passwd command would be described iti Section 1, while 
the passwd file would be described in uSection 3. The 
.specific man pages would normally be referred to as 
“passwd(l)” and “passwd(5}“. By default, the man 
command will display the first page it finds, going in 
ascending order through the sections. You can make .stire 
that you get passwd(5), however, by typing “man 5 
passwd". Try it! 

Unlike the hierarchical “help .sy.stems^ as found on 
Cicso routers or operating .syslcrns such as VMS, man pages 
I lave nt) automated support for navigation. Some 
experimental variants use H'l'Ml. to display man pages, 
Uirning SEE ALSO entries int<i hyperlinks. Mast man sy.slcms, 
however, require that you do your t>wn navigation. 

Pari of the reason for this lies in the sheer scale of the 
B.'SD command set. '1 liere are .several httndred c:ommancls 
and ihousantls of functions. Trying to place them all in a 
meaningftil hierarchy (or even defensible topical groupings) 
is not a trivial task! Nonetheless, some help is available. 

To find a man page wltcn you don’t know the exact 
name, use apropos(l). It displays ail the “NAME" lines that 
contain the specified text strings, if you are trying for a 
text siring ihal contains non-alpliamimcric cliaracters, he 
sure to enclose I lie string in quotes. Otherwise, you 11 get 
all lire pages that match any “word" (i.e,, sequence of 
non-blank character.s) in the string. Mere arc some 
inieresting uses of tlie apropos command; iry them out! 

[1 ocalhost rdrnX apropos device 
[localhosi:rdm% apropos dev 
[localhost : ~J rdmTC apropos *(4)" 

Iiocalhoat:~] rdm% apropos *file system' 
jlocaJhostrdm% apropos file system 

Although BSD provides several hundred tommands, 
only a few^ are needed for everyday use. Next month, 
we'll look at some basic BSD commands, as well as a 
smattering of shell (command line interface) syntax. 


32 


Tm BSD MajN Paces 


MaOTech • Ai^kil 2002 







Without this piece, 
you’re not done. 

It’s not enough just to write solid code anymore. Users expect 
an easy-to-use installer when they buy your software. 

InstallerMaker gives you all the tools you need to install, 
uninstall, resource-compress or update your software in one 
complete, easy-to-use package. 

Add marketing muscle to your installers by customizing your 
electronic registration form to include surveys and special 
offers. Even create demoware in miniita!. 

Visit http://www.stuffit.com/installermaker/ to also 
learn about creating Mac® OS X compatible installers with 
InstallerMaker. 

Then you’re done. 

The complete installation and distribution solutionr* 



Get your beta testing started faster. 


Guarantee your builds arrive safe and 
sound! New Stulfit 
Express'^automates file compression 
and transfer tasks to eliminate costly 
errors every time you exchange data. By 
creating custom drop box applications, 
you and those you communicate with 
can accomplish complex file transfer 
tasks with a simple drag and drop. 
Choose from up to 26 file transfer steps 
with no coding required. Boost 
productivity and save time by 


distributing your custom Express boxes 
to everyone on your list. 
http://www.stuffit.com/express/enterprisemac. 



Express" Box 


© 2003 Aladdin Systemst Inc. (831) 76l-6200www.33addinifjy5.com. InstallerMaker and Stiifflr Express arc trademarks of Aladdin Systems, IntL 











QUICKTIME 

TOOLKIT 


hy Tim Monroe 

Big 


Playing QuickTime Movies Fullscreen 


Introduction 

It's sometimes remarkeci that when QuickC inie was 
first introduced, it was able lo play movies that were 
only about the size of a postage stamp. U turns out that 
this isn't quite true. 1’he very first Quick'l'ime CD.s 
distributed to software developers contained a number 
of sample movies that are 320 by 2^0 pixels, or just 
under 4.S by 3*'^ inches (which is significantly larger 
than any postage stamp I’ve ever seen). What is true is 
that certain kinds of movies — in particular, full- 
motion movies encoded using the video compressor — 
had to be kept small in order to achieve a reasonable 
frame rate on playback. These kinds of movies 
typically had Lo f^e somewhere in Uie order o\' 160 Ijy 
120 pixels to get a playlxick rate of aboiu 12 frames per 
second. Not great, hut pretty good fc^r a software-only 
nic^vie playback system on a Mac ll in 190L 

Since then, computer hardware and software 
technologies have advanced to the point that 
Quick'rime can achieve smooth playback for much 
larger movies, at frajiies rates of 24 to 30 frames pet- 
second (or even greater). Prom C^iitck^'ime version 2.1 
onward, it has al.so been possible to play QuickTime 
movies l>ack /h//scrce«, so that the movie occu[iies an 
entire screen. Pigure 1 shows a frame of a movie being 
played hack fullscreen; as you can see, there is no 
menu bar and the window that contains the movie 
does not have a window frame or title bar. In addition, 
the control strip (on classic Mac operating systems), 
die dock (on Mac OS X), or the taskbar (on Windows 
operating systems) is hidden while a movie is playing 
fullscreen. At its natural propcjrtions, this movie does 
not completely ftli the screen, so ids centered 
iKjri/onlally with llie edges drawn in black. 



figure /. A QuickTime mome flayed fuiiscreefi 

Pullscreen movie playback is fairly common in games, 
especially ftjr the cul-sccncs that occur hetween game levels. 
It has also recently become popular for many of the movie 
trailers posted to the weh in QuickTime format. 

In this article, we re going to learn how to play QuickTime 
movies fullscreen, I mentioned in an earlier article ('*1’he 
FlaslT, in MacTech, January 2002) ihai fullscreen movie 
playback is accomplished primarily using the two functions 
BeginFuilScreen and EndFullScreen. When using these functions 
to integrate fullscreen playback into our sample applications, 
however, well need to pay attention to a number of issues, 
including saving and restoring the state of our movie windows 
and their associated movie controllers. We also want to take a 
look at the wired action introduced in QuickTime 3.0d iliai a 
movie can use lo begin and end fullscreen playback. Along the 
way, we’ll touch on a few topics of general interest to 
QuickTime developers, including time base callback functions. 


Tim Mofiroc in a member of the QuickTime engineering team. You can contact him at monnx^©apple.com. The view.s expressed here are not 
necessarily .shared hy his employer. 
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Our sumple applitalkin this month is called 
QTBigScrccn. As usual, it's l)ased on the QTShcll sample 
application and adds support for entering and exiting 
fullscreen mode. The Test menu of QTBigScreen is shown in 
Figure 2; it contains just one item, which allows Lite user to 
put the front most movie window into fullscreen mode. 



Figure 2: We 7to menu of QTBigScreen 


There is no menu item for exiting fullscreen mode; instead, 
well follow the example of Quick! ime Flayer and return to 
I he normal wimlowed mode wtien ifie user types the Escape 
key or when a nondnieractive and non-lt>opcd movie 
reaches the end. 


The Theory 

Let's begin by taking a look at the BeginFullScreen and 
EndFullScreen functions. As I mentioned, things tend to get a 
tad lengthy when we use these calls in a reahjife application, 
so it's good to have a firm grasp on how iliey work before 
we try to do that. In thi.s article, we are going to focus on 
using these functions to play QuickTime movies fullscreen, 
but they can in fact he used to display ciny kind of content 
in a fullscreen w'indow. Moreover, we can use these 
functions simply to change the resolution of a screen, 
without wanting to take over the entire screen. In short, 
there’s a lot going on with these tw'o functions that we need 
to understand clearly liefore we attempt to use them in our 
applications. 


Entering and Exiting Fullscreen Mode 

Ttie BeginFullScreen function is declared essentially like 

this: 

OSErr BeginFullScreen ( 

Ptr ^restoreState. 

GTiHundlc whichGt), 
short MesirettWidth* 
short 'desiredHeight. 

WindowRet 'newWltidow, 

RGBColor *eraseColor. 
long flags): 


The key inpui parameter.s are desired Width and 
desiredHeighl, which are pointers to ihe width and height of 
the movie (or image, or other content) that we want lo 
display fullscreen. BeginFullScreen creaie,s a new window 
Lfiai is at least that large and returns a window pointer for 
that window in the location pointed to by the newWindow 
parameter. BeginFullScreen also erases the screen (using the 
color specified by the eraseColor parameter) and (depending 
on the value of the flags paramcier, which we’ll consider in 


a moment) hides the menu bar and control strip. The 
whichGD parameter indicates wfiicli graphics device we want 
to put into fullscreen mode; we shall always pass the value 
NULL to select the main screen. 

BeginFullScreen also returns, through the restoreState 
parameter, a pointer to a block of memory that contains 
information on how to return from fullscreen mode to normal 
windowed mode. We exit fullscreen mode by passing that 
pointer to EndFullScreen, which is declared like this: 

OSErt EndFullScreen (Ptr fullState, long flagfj) ; 

Note that the restoreState (or fullState) pointer is opaque and 
is owned by QuickTime; we shouldn’t do anything with it 
excepi pass it to EndFullScreen when we are ready to exit 
fullscreen mode. Similarly, the newWindow window pointer ivS 
owned by QuickTime, which will dispose of li after we call 
EndFullScreen. 

The flags parameter passed to EndFullScreen is unu.sed 
and should be set to 0. The flags parameter passed to 
BeginFullScreen controls several aspects of fullscreea mode. 
Currently we can use these constants Lo set the value of this 
parameter: 

enum \ 

fuUSerGenn ideCursor - II << 0, 

ful 1 ScreenAnowEventg ^ IL << 1, 

CullScreenDontChangGHGTiuBar = IL << 2. 

fullScreenPrefliahtSl 2 e - IL << 3 

1: 

The fullscreen HideCursor flag indicates that BeginFullScreen 
should hide the cursor while the screen is in fullscreen mode. 
This is useful if we jnsi want to play a movie fullscreen from 
start to finish, but it's less useful for interactive movies [)layed 
fullscreen. In QTBigScreen, we will not set this flag when we 
call BeginFullScreen. The fullScreenAllowEvents flag indicaie.s 
that our ufjplication intends to allow other open applications 
to receive processing time; in general, we should set this flag. 
The full Screen DontChangeMenuBar flag indicates that 
BeginFullScreen should ntji hide the menu bar. 

The fullScreenPreflightSize flag is of particular interest. If 
we set this flag, then BegfnFulfScreen does not change any 
screen settings and does not return a new window lo us. 
Instead, it returns, through the desiredWfdth and desiredHeight 
parameters, the width and height that the screen would have 
been set to if the fullScreenPreflightSize flag had not been sel. 
We can u.se that Hag to determine the size of the fullscreen 
window without actually entering fullscreen mode. 

Changing ihc Screen Resoluliem 

Why is this useful? Recall that BeginFullScreen w'ill create 
a window that is at least as large as the height and width we 
pass it. In addition, BeginFullScreen will change the screen 
resol LI lion to the closest resolution that contains that window. 
If, for instance, the main screen is originally set to a 
re.solution of 1024 by 768 and if we pass a width and height 
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of (say) 762 and 560^ then BeginFullScreen will duinf'c the 
resolution of the screen to 800 by 600 (assuming that the 
mtmilor supports that resolution). 

We can exploit this behavior in several ways. First, we 
can use BeginFullScreen to deicmiinc the eurreni screen 
resolution. If wc set 0 to be the value pointed to by both the 
desiredWidth and desired Height parameters, then 
BeginFullScreen leaves the dimensions of the screen 
unchanged hut returns to us the current dimensions of the 
screen in the locations pointed to by those parajneters. If we 
also pass the fullScreenPreflightSize Hag, then BeginFullScreen 
doesn't change any of the current screen settings. The end 
resuh (s that wc are given tlie current height and width of the 
screen (that is, its resolution), listing 1 defines the function 
QTUtils_GetScreenfiesolution, which retrieves the current 
restilution of Uie main screen, 

listing 1; Getting the current resolution of the main 
screen 

QTLitils 

OSKr r QTU til l Sc tec ri Rcso Inti on 

(short ‘thePlxelstloriK, short 'thePixelsVert) 

{ 

Ftr myDuiwnyPtr “ NULL: 

OSRrr inyErt = noErr; 

if {(thoPixplBHDrlK = NULL} || (thePixelsVert -- NULL)) 
cyuifirtpuraraEr r): 

’“thoPixeisHoriK - 0: 

•thePixelsVert 0: 

nyErr " BeginFullScreenUmyDuinmyPtr, NULL* theFixelalioria. 
rhcPixelHVert. NULL* NULL. fuliScreenPreflightSlze); 

return(myEtc); 

1 

Notice tliat we need to pass the address of a variable of type 
Ptr as the first parameter to BeginFullScreen, even iluHigh it 
does not return an actual pointer in that location. If we look 
at the value of myOummyPtf after calling BeginFullScreen 
liere, weMl see that it's still NULL. So there is no need to call 
End FullScreen to di.spose of that pointer. 

We can also use BeginFullScreen to change the screen 
resolution without hiding the menu bar. We simply pass in 
the desired height and width, and we .set the flags parameter 
so that the menu bar is not hidden. In this case, we need to 
pass the value NULL for the newWindow parameter, indicating 
that we don't want a new window to be created. Here’s how' 
we could set the main screen to a resolution of 800 by 600: 

myllejrlzPixels ^ 800: 
myVerrFixels = 600; 

!DyEt:i: * BeginFullScreen[igKestoreStaLc* HUia** 

^myKorixPixels* SayVertPlxels* NULL* NUt.Ti* 
fullScreenDontChangeHeniiDar); 

We need to keep track of the restore state so that we can 
undo the resotiitioil change at .some future time. You slum Id 
keep In mind that there i,s no way to suppress the hiding of 
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the control strip (or dock or taskbar) when you call 
BeginFullScreen, If you want the control strip (or dock or 
tuskljar) to remain visible after you adjust ihe resoluiion, 
you'll need to programmatically reshow it. (For instance, on 
Windows you could call the QTML function ShowHideTaskBar 
to reshow the taskbar.) It would be nice if QuickTime 
defined a flag that would allow us to request that the control 
strip (or its ilk) remain visible after a call to BeginFullScreen. 

Scaling the Movie 

!o QTBigScreen, we clon/c want the resolution of the 
main screen to be changed when we play a movie fullscreen. 
We can accomplish this by scaling tlie movie so that the 
requested sixe is large enough to occupy alt or almost all of 
the main screen at its current resolution. So weVe going to 
end up calling BeginFullScreen twice, once to get the current 
resolution (as we did in Listing 1) and again to put a movie 
window into fullscreen mode. But before we call 
BeginFullScreen the second time, we need to do a little 
mathematics to figure out how to scale the movie so that it 
retains its original aspect ratio but fills as much of the screen 
as possible. 

We begin by calling BeginFullScreen to gel the current 
resolittion of the screen: 

short BiyScreenWidth ^ 0: 

short rayScreenHelght “ 0: 

myRrr = Bo^inFulIScrcciU&t*'myAppData).fResioteState* NJLL, 
&inyScrooRWidLhi femyScreenHeight. I^ULL, NULL, 
fuliSrreenl^ ref llghtSize); 

As you can see, we are storing the restore state in the application 
ilata rc‘conJ. (Iliimately weTe going to have to maintain aliout a 
dozen pieces of data in that record (which we'll encounter 


slumly). Once weVe retrieved ihe curreni re.solution, let's make 
a copy of that iJifomiation: 

nyUrigSereenHeight “ rayScreenttelght i 
nyOrigSerfienWidth = uyScrccnWtdth; 

Now we need to get the natural size of the movie we want 
to play fullscreen. We can do this by calling 

GelltovieN^ 

Getf1ovieHaturalBnufjd.^Rcct (myHovie. kiyKecl): 

HafiOf ffiet.Rficf. (i^iiiyltect, tnyRert. lef t, myRect »top) I 

iryHovleWidth = myRect. right: 
myHovieJIeight = loyRect. botTOJnj 


(Calling GetMovieBox here wouldn't work fjuite right, since the 
user might have resized tlie nu>vie window iKTore putting it into 
fullscTt^en mode.) 

And now wc can calciilaie the aspect nitios of the screen 
and the movie: 

nyKovieRatio = FixRatiotmyHovtpWidih, wyttavielkighLj: 
tiyScrefMiR»tto “ FlxRatifi(fliySr recfrWid 1 h » myScreenUeight) : 


We use these ratios to determine which dimension of the movie 
sitould lie scaled to completely rill the corresponding dimension 
of the screen. The math retjuired is simple: 


If tmyMuvieRatio > inyScxeenRaCio) I 

myHovieHeight - tmyScreenWidth * myMovicHeight) / 

t]iyHnvip.Vldth; 

layMovl^Width “ myScreenWidth; 

I D 

rayKovl^^Width “ (rayS^rreenlloight * jnyMovU'Wldth) / 

TiyHovieHeight: 

inyHovietieight = myScreenHpiight: 

I 

At this point, w'e kmiw the desired size of the movie and 
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lienee we can call BegifiFullScreen once again: 

myScreettWidth * tnyMovieWidth; 
myScreenHelghf ** myKovIpRi^ i ghl: 

fliyErr Bi.’ginFul!ScreeR(&{ * *tnyAppOata}, fRestoreState, MULL, 
^oiySc [eenWid th, fcniySc reenlleight, 

A t *‘myAppData).fFullScreenWindow, &fflyColDt, 
fullScreenAlIowEvents): 


If Begin FullScreen returns sucTessfuIly, then 
(**myAppData).fFullScfeenWindow contains a window iK>imer to 
the new fullscreen window and my Screen Width and 
myScreenHeigbt point to the actual width and iieighi of that 
window. If the aspect ratio of the movie does not exactly match 
that t>F llic screen^ then we need to move the movie down or to 
the right so that it is cenlered in tlie fullscreen window (see 
Figure I again). First we set the movie's rectangle: 

HacSetRectC^JayRect, 0, 0. myMovieWldtti, myMovieHeight) j 

And then we nudge the movie down or to the right to center ii 
on the screen: 

HacOffsetRect (imyRect * (my Sc teen Width ■ nyMoiiri^eWidth) / 2, 
(myScreenHeight - uyKovieHeight) / 2J: 

SetKovieBox (myHovie, &tiiyRect): 


Tliere is one final ^golclia*’ we need to warch otn for. 
Although we scaled the movie up so that one of its 
dimensions extends for the full width or height of the screen, 
it's possible liial the expanded movie sixe exactly matches a 
screen resolution that i.s not the same as the original .screen 
resolution. Suppose, for hislancc% that our movie has a 
natural size of 4H0 by 560 pixels. This movie, when scaled 
lip, will exactly fili a screen that is 1024 by 768.1 low'cver, the 
"megawide" screen on the Titanium PowerBook lias a natural 
resolution of 1152 by 768, and it also supports the restilution 
of 1024 by 768 (fiy Idanktng 64 pixels on the left anti righi 
sides of the screen), If w-e play this movie fullscreen on that 
PowerBook, our existing code will result in the screen 
restjiution being changed to 1021 by 768; in that rase, there 
is no need to nudge the movie down or to the riglu. 

So before we adjust ihe movie's rectangle, we should 
check to see w'hellier the screen resolution did in fact 
change. We cleverly saved the original screen resolution, and 
our second call lo BeginFullScreen gives us back the current 
screen resolution; we can compare the curreni with the 
original and then nudge the movie only if tlie restdiuion has 
not changed: 

if ((inyScreenWidth = myOrlgScreenWidtK) && 

(fflyScreenHeight siyOrigScreeiiHeight)) 
MacOffsetRect (&aiyRect ♦ (myScreenWidth - rayMovIrWidt h) / 

2 , 

(myScreenHelght - myHovtrHDighO / Z): 

Once again, ii might Ik* nice if BeginFullScreen supported a 
Hag dial instructed it nol to change the screen resolution. 


The Practice 

So, we now underslami how to use BeginFullScreen and 
EndFullScreen to enter and exit fullscreen mode. We've seen 
how to request a fullscreen window size that makes our 
movie as laq^e as possible while preserving its original aspect 
ratio and also preventing changes in the screen resoluTion 
(whenever possible). And weVe seen how to adju.st tlie 
movie box — the rectangle in which the movie is drawn 
inside its window — so that the movie is nicely centered in 
the fullscreen window. AreiiT we dune yet? 

No. There are still a couple of issues we need to address. 
Our basic sample applicaiicm iTamework was not developed 
with the intention of supporting fullscreen nirwie playback, 
so a couple of our framewwk functions need some minor 
iweaking. More importantly, we need to keep track of some 
information (including the restore informalion and the new 
window pointer) for each movie window we put into 
fullscreen mode. And of course, w-e need to make sure that 
events gel pas,sed lo a movie playing fullscreen. In this 
section we'll tackle these issues. 


Initializing the Movie Window Data 

Ideally, we'd like the user lo k* able lo pul any of our 
application's movie windows into riillscreen mode and then 
hack into n<>rinal mmic. We therefore need to keep track of the 
rest ore state information and ihe new window pointer returned 
by BeginFullScreen, as well us a few other pieces of inh)rmaLion. 
We'll define a custf>m application data record, like this: 


lypedef struct ApplicationDataRecord I 
WindowReference fOrlRWindow; 

^/iudowPtr fFullScrcGnWtndow: 

Ptr fRefitorcStatf: 

GWorldPt r fOrigHavicCWorId: 

Rect fOrigMovleRect: 

Reel tOrlgCpnttolierRect: 

Houlean 1 QrigCont rollerVis: 

Boolean fOrigControileirAttached: 

QTCailBack fCallBack: 

QTCailBackUPP fCallBackUPP: 

Boolean fEiidPtlllncr eenNondod; 

Boolean fnt^si royWl nilowNeoded : 

I Appl IraT toiil)iitnRt*rf>rd , *A|)p] icai ionlJataPtr, 
* *Appl teal ionilalalJdJ : 


The fOrigWindow field will contain the original window 
reference — iliai is, a reference io I lie window that the user 
puts into fullscreen mode. (RemernlKT lhai the aclual tyi>e of 
I his object varies; on Macintosh systems, it’s of type 
WindowPtr, while on Wintlows systems it’s of type HWND.) 
The fRestoreState and fFullScreenWindow fields Itold the 
restore state and window pointer returned by 
BeginFullScreen. The next five fields hold information about 
ihe state of the movie window at the lime it's put into 
fullscreen mode; for instance, the tOhgMovieRect field holds 
the movie rectangle, and fO rig Cent roller Vis indicates whether 
the eontroller bar was visible when we called 
BeginFullScreen. Well need these pieces of information when 
we restore the movie lo its normal windowed slate. 
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Tiic fCallBack unci fCallBackUPP Helds hold information 
relaied to a time base callback function; we use this function 
to automat tea lly return a movie from fullscreen state to 
normal state when the movie reaches the end, to mimic the 
behavior of QuickTime Player. (I perscmally d«)n't like this 
behavior, hut it's useful to know how to implement it. Tve 
conditionalixed the callback code using the compiler macro 
END_FULLSCREEN^AT_MOVIE„ENO, so it's easy enough to 
turn off,) 

The last two fields of our application data structure are 
boolean values tliai indicate whether the associated movie 
window should be returned from fullscreen mode to normal 
mode and whether the associated movie window' should be 
closed, later well see why we need the.se Helds. 

I’m also going to introduce a global variable that holds 
the window object for the window that is currently in 
fullscreen mtjde: 

WitidowObjecL gFuliScteenWitidowObJect * NULL: 

II would be possible to determine which, if any, movie 
window is in fyllscrecn mode by iieraiing through all open 
movie windows and checking their application data record 
(to see if fFullScreenWindow is non-NULL), but using a global 
vanal)le will simplify our code. 

When we first open a movie window, we shall call 
QTBig_lnitWindowData (Listing 2) to create this custom 
application data record and initialize its Helds. 

Listing 2: InitiaiizlBg appJUcation-spccinc window data 

n it Wimk w l hira 

AppilcationDataHdl QTBig^TRlrWtndowData 
(WlndowObJect rheWlndowObject) 

I 

AppllcatignDataUdl jcyAppData = NULL; 

// if wr jtrr:Ldy liavt: stnitt: wimkiw daUrdump it 
myAppBata “ (ApplicationDatalldl) 

QTFrame GetAppDataFroaWlndowOb jccL (lh{?WlndowObject): 
if tmyAppData t“ MULL) 

QTSlg^ DuiiipW i tidownaiu (iheWiridovObject}; 

// albK'itf a new applioiiim duu luridJc 
myAppDaLa (ApplicatianOataHdl) 

Newllatid leC lea r (eizeof (Appllca tlonBataReco rd)); 

returnEroyAppData): 

1 

And w'hen we close a movie window, we want ItJ deal locale 
the applicaiion data record. For ihis^ we call the function 
QTBig DumpWindowData, defined In Listing 5- Notice that we 
first check to see whether the window is in fulLscreen mode; 
if it is, we call our function QTBig.StopFullscreen to retuni it 
to ncjrmal mode. 

LLsling 3: Destroying application-specific window data 

QTBijel)ump’'»1rHkiwna!a 

void UTBig_DumpWindovI>ata tWindoiiiObjact thfftfijndcuirObject) 

I 

ApplicatioabatflHdl wyAppOara = NULL: 

rayAppData = (AppUcaLloaUataHdl) 

tjTFraine_Ge t AppDataFromWind owOb] ect (theWitidowOb ject): 

If (atyAppUata (- NULL) [ 


if (t’'myAppUata) .fFullSrteentfihdou I- mu.T.) 
QTBi g_S t opFiii i sc r een (tb eW 1 n d owOb j c c t); 

DlsposeHand 1 Cl t (Handle)i^yAppData); 
(“theWlndotfObjecO ■ fAppData “ NULL: 

I 

1 


Entering Fullscreen Mode 

Let's revisit For a moment our basic scheme for opening 
movie windows and keeping track of window-specific data. 
On Macintosh systems, we call NewCWindow to obtain a 
window pointer to a new window. We allocate a new 
window object record and store a handle to that record as 
the window reference constant (by calling SelWRefGon). This 
alk>w.s us to retrieve our windtjw-specific data (the movie 
I icing displayed in the window, the movie controller 
associated with the movie, and so Forth) if we are given the 
window pointer On Windows operating systems, we call 
CreateWindowEx to create a new window and SetWindowLong 
to store a handle io the window' record in the window's data. 
(See "QuickTime 10T in Af£/c7ecjfi, January 2000 for a more 
complete account of all this.) 

Now, our entire application framework assumes that 
each window displayed by our applicaiion is associated with 
a window object record. We need the data in that record tij 
know which movie or image is contained in the windtnv, 
whether the nuivie cjr image has fiecMi changed since it was 
lu.st saved, and similar inftirmalion. So, when BeginFullScreen 
rettirn.s to us a new' fullscreen window, we need to attach a 
window (jbject lo lhai window. We could, of course, create a 
new window object and aUach it to the window, but things 
actually work much better if we borrow the window object 
from the movie window we w'ant to pm into fullsCTeeii 
mode. We'll do iluu like ihis: 

Iif TARGET_OS_MAC 

SeLURefCu:i( (* *aiyAppData). 1 FullScteenliltido¥. 

(Igtig) theWindowObfect): 

#if TAHGET_ 0 S_W 1 N 32 

Se tyind owLon g{Ce t Pa r t Na 11vrWin d ow{ 

CGrafPtn t* *myApp|)ata) . fFullScrcicnWiiidaw) . 
Gyi.._USKRDATA, (LPAKAM) tht’WirtduwObject): 

The Macintosh code is .straigliiforward: simply set the 
reference constant of ihe window cfeaied by BeginFullScreen 
to the window object passed lo QTBig_,SlaftFullscreen. The 
Windows code is a little iimre involved, since BeginFullScreen 
reiuros to us a window pointer (of type WindowPlr) but our 
Windows application expects a movie window to be of type 
HWND. Accordingly, w-e need to call GetPoflNativeWindow to 
get the native window (of type HWND) that is as,sociated with 
the windt)w pointer. Tliis window was created amomatically 
by QuickTime when it created the fullscreen window. 

Keep in mind that we now' have two windows to worry 
ahooi: (I) ihe original movie window (which is either of type 
WindowPtr or HWND, depending on ifie native operating 
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system) and (2) a fullscreen window {which is always of type 
WindowPtr hut which on Windows is also associated with a 
window of type HWND). We are attaching the window object 
assoduied wiUi the original movie window to the fullscreen 
window; this lets us know which movie to play fullscreen 
and how to control that movie; ifs also important to have a 
window object available when we want to pass events to the 
fullscreen movie (as well see shortly). 

It seems reasonable that once weVe created the 
fullscreen window, we should hide the original movie 
window; after all, we won't be able to redraw the original 
movie window or let the user move it around* We can liide 
the movie window like this: 

QTFraiiie_SetWindowVisState (theWindowObject, false) : 

The QTFrame.SetWindowVIsState function is a new function 
that we need to add to our framework; it's defined in listing 
4 - 

Listing 4: Showing or hiding a movie window 

QlTruJK.SctWinduwVLsStiilc 

void (ITFraine^SetWiudowVisState 

(WindowObject theWlndowObject, Boolean theState) 

I 

U make swr we have a ncin-Nt ILI. window object mil window 
if (theyindowObject -- NULL) 
return; 

if {(* * theWindcJwObject). fWindow = MULL) 
return: 

// ,set the visjbUit) state of the window 
#if TARGET OS MAC 
if (theState) 

MaeShowWindov t(* *IheWindovUbject).fWindow); 
clue 

tlide^ltidpwC(* *the¥iridowObject) .fWindaw): 
tfendif 

#if TAHGET_OS_WIM32 

ShowMindowC (•*the¥indowObjecr;) . fWlndow, iheStaie) : 
i^endlf 
) 


(It's inlercsltng to note that Quick'rime Player df>es iu>t hide 
the original movie window after putiing it into fullscreen 
mode. What’s up with that?) 

There is one final set of tasks we need to attend to w'hen 
putting a movie window into fullscreen mode, As we’ve 
seen, we are using the same movie and movie controller in 
the new fullscreen window that we use in the original movie 
window. Bill of course die lullsc reen window has a different 
graphics world and a different size. So wc need lo save die 
graphics world, size, and a few other pieces of information 
[)efore we go into fullscreen nitKle and laier restore them 
when we return to normal mode, QTBig_StartFullscreen 
ctmtains these lines to save the relevant information in our 
application data record: 

GetHov IcGWorldfroyMovle, $( * 'icyAppData) *fOrigMovieGWorld, 

MULL): 

GctMovieBujttmyMovie, 'myAppData) .fOrig)iovieRect); 

MCCetCont rolierDoundsRect (tnyHC * 

it* '(nyAppData) *fOrigControllerRect): 

(* *DiyAppData) .fOrigCont roUt^rVia ” MCGotVlsiblefnyHC) : 


(*“myAppData).fOrigControllerAttached “ 

MClsCont rolie rAt tached(nyMC): 
t * * niyAppData).fOrigWindow “ C * * theWlndowObJect), fVindow; 


Once we’ve successfully entered fullscreen mcxie, we need 
to set the movie graphics world, movie controller bounds, and 
so forth for the new fullscreen win<low: 

SetGtforld fGetWindowpQrif (* *tayAppData) ♦ f Full Scree nWin do v), 
NULL); 

SetMovieGWoridtmyMovie. 

CetWindowFort{(*'myAppData)* fFullSc teeuUindow), NULL): 
MCSetControllerPort (layMC. 

GetWindowPort C {**TiiyAppData) *fFultScrep-uWindow)} ; 
MCSetContrellerAttaohed(iiiyMC* falee) ; 

MCSetControllerBoundaReot (tuyMC* SunyRect) ; 

MCSetVisibletinyMG. false); 

HCActivatetniyHC, [* *fliyAppData) .fFullScreenWindov, true); 


We also need to set the fWindow field of the window object 
record to the new fullscreen window; 

t * ‘theUi ndovObjeet). f¥ i ndow 

QTF r am(>_C e t Wind owH e f e c en c e F r omW i rid ow ( 

|**]nyAppDplii). fFullScreenWlndov); 


And we want to keep track of the Fullscreen window in a 
global variahie; 

gFullScreenWiridcjwObJect ” tlieWindowObject: 

We are finally ready lo take a look at the complete 
defiriiiion of QTBjg.StarlFullscreen, shown in listing 5. 


Listing 5: Entering fullscreen made 

Q ru jg^Sian I' uJ IstTff n 

OSErr QTBig_StartFuiiscreen (WindovObfect theWindowObjact) 

[ 

HovieController oyMC * MULL; 

Movie nyMovIo “ MULL; 

Appl icationlSataHdl nyAppDola = NULL; 

long nyFlugs ■ fuilScreenAllowEvents; 

OSErr nyErt - paramErr; 

if (thcWiudowObject “ NULL) 
goto bait: 

rayAppUata = (ApplicatloftDnt aHdl) 

QTFraifle„GotAppDai aFr omW 1 ndowOb Jyc l {I huWiridowObj eo L) : 
rayMovio = E*'tht^WindowObjcel). fHovie; 
myMC - (*‘thcWindowObjoct).fConiroiler; 

if (itnyAppData = NULL) || fmyHovi.e NULL) || 

EniyHC -- NULL)) 
goto bail; 

If ({-*myAppData)*fFul ISOrennWI Fiduw = NULL) [ 
pborl (nyOrlgScreoftWidtli * 0; 

short oiyOrlgSyreenlliJight = D; 

short ntyNovSereenWidth “ 0; 

short myNevScreynHelfeht “ 0: 

short ntyScreonWidtb * 0; 

short my ScreenHeight ^ 0; 

short myMovioWidth " 0: 

short myHovloHc!ghr ^ 0; 

Fixed myScrGeiiRaiio; 

Fixed myHovieKatio; 

Reel nsyRect: 

RGBColor layColor - iOxOOOO. 0x0000. 0x00001 ;//blm:k 

// rcmemljcr some of tin** curn^tii suiie 

GetNovioGWorldErayMovle* &(**royAppbaia).fOrigMov1cGWorld. 

NUIJd ; 

GelMovifBox(myHovie» ‘ *»nyAppData).fOrigWovieRect): 
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HCnetCotitrt3llerBo\:ndBReGt (inyMC. 

&[**myAppData) ^fOrigControllerRect) ^ 

C*'myAppnata) .fOrigControUcrVis = MCGetVislble(myMC) : 

C* 'niyAppDiita), fOrigControUerAt tached = 

MCI sControll^rAttached (inyMC) 

C*'myAppData) *fOrigWindow ^ {**thsWindowObject) .fWindou: 
// gGt Uic oirrt^flt soceii rtfSDlutitjfi 

iryErr = BeginFtillScreen(?k( **niyAppData), fRestoreState, 
MULL, tisyScreenWidth. &myScreenHeight. NULL. NULL. 
fullScreenPref 1 ightSir.e): 
if {myKrr !- noEri) 
goto bail: 

// kctp track of die original iicretti ttsoluUoii 
myOrigSereenRaight = myScraenHeight; 
myOrigSereenWidth ” niyScreenWidth i 

// cjik'ulaTf chc dminatiou rectangle 
OetMovieNaturalBoLmdskect (loyMovieH imyRecc ); 
MacOffsetRectl&myRect, 'myRect.left. jnyRect,top): 

inyMovieWidth inyRect.right; 
rayMovieUeight = myReet.bottom; 

ffiyMovieEotio = FixRatio(rayMovieWldth. inyMovleHeightj: 
myScreenRalio = FixRatioCmyScrecnWldth. myScreonUaight)r 

// iicaic die movie recyiigle to fit die screen ratio 
if (inyMoviaRatio ) myScreenRatio) ( 

rnyMovieHeight “ {myScreetiWidth * rayMovieHeight) / 
myMovieWldth: 

myMovioWldth "= myScreenWitlLh; 

I else { 

myHovieWidth = (myScreenBeight * jnyMovieWidth) / 
rayMovieHeight: 

myHovieheight “ myScreenHeight; 

1 

MaeSetRect{i&myRGCt. 0. 0, myMovieWldlli. niyMovielleighl.): 

myScreenWidth = inyWovi e Width: 
raySereenHeight = rayMovieHeight: 

// ticgiti ftiU'SCiceti display 

rayErr “ BeginFol IScreen (Sr f *'myAppData). fRestoreState. 
NULL. l^juiyScrcenWldth, SsmyScreenlleight. 

Sr(* *iiiyAppUata). CFullSereaoWindow. ^myColor. 

inyFlags) : 

if (myErr 1^ noErr) 
goto bail; 

// deiermine whether die resolution changed; if it lias changed, we nuisi have 
// passed in a supin>rted resoliitiim^sti we waor the movie to fill the screen; 

// otherwise, we need to offeci the movie tc^ ctmter ii in the scieefl 
if {(myScreenWidth = rayOrigSereenWidth) hh 

(niySeteenHeight — myOrlgScreenHeight]) 

MocOffset Rect(SrayRe c t. 

(myiicreenWidth ' myMovleWidth) / 2. 
(rayScreenHeight - rayMovieHeight) / 21: 

//if TARGET_0!;_WIN3?. 

// (in Winikiw-S, wt a window pitKeitlorL* for the lu^ window 
QTMTLSotW! ndowWiidProet (* *myAppUata). f Ful iSe reenWindow. 
QTMe llandleMeasages) : 

// hide die origin:J window 

QTFrame SetWindowViaStatefthcWindowQbject. false): 

// attach the existing window object to the new window 
/Ilf TARGET_OS^MAC 

SeiWRefCon{(*'myAppData),fFullScreenWindow, 

(long)theWindowObiset): 

ilendif 

//if TARGET_OS_WIN32 

SetWindovLnng(GetPo rrUa tivcWind ow( 

(GrafPtr) (*’niyAppDaia) . FFul iScreenWindow) * 
GWL^USRRDATA. (LfARAM)theWindowObject): 

tfe.ndi f 

// set the movie and movie controller state to the new wind<w and rc'CiangJe 


SetCWorld (GetWindoirfFort (t * ^inyAppData) .fFnl 1 ScreenWtndoiwl . 
NULL): 

SetMovieGWo r1d(rayMovIc. 

GeLWindowPorL((*'myAppData).rFullScreenWindow). 

NULL): 

MGSetControI lerPort (inyMC, 

GetWindowPort C(* 'myAppData} .fFuilScreenWindow)}; 
MCSetConttroilerAttached(niyMC, false): 
MCSetControllerBoundsRect (rayMC* AitiyRect) ; 

SetMovIoBoxCmyNovie. {irayRect) ; 

MCSetViaibleCniyHCH false): 

MCActivate(myMG. ('‘myAppOata).fFullScreenWindow. true): 

(** theWindowObject)-fWitidow = 

QTF rame.GetVindowRaferenc eFromWindow( 

(* •myAppData). fFullScreenWinflDw): 

//if TARGET_API_MAC_CAREON 

HiliteWindow( {‘ *ntyAppData) .fFullScreenWindow* true): 

//end if 

f/if END_FDLLSCREEN._AT_ MOVIE END 

// install a callliack pnjccdure to return linear, non-lixiping movies 
// to normal mtxlc at the end of the movie 
if [QTBig_MovielsStoppable (inyMC)) 

liTBig_installCallBack(theWindowObject): 

//end if 
f 

gFullScreenUindoivObject = theWindowObject: 
bail: 

return(myErr): 

I 

Ytju'll notice u lew lines of code we haven’t discussed 
ycL The Windows-only call to QTMLSetWindowWnciProc is 
necessary to hnnclle messages targeted at the fullscreen 
window, as we’ll see in the next section. The Carbrm-only 
call to HiliteWindow ensures ihat the window returned by 
BeginFullScreen is highlighted. (Apparently, in some 
circumstances, that window' Ls occasionally unhighiighied, 
which blocks any interactivity in the movie.) And the code 
selected by the END^FULLSCREEN^AT.MOVIE^END flag 
installs a time base callback function that returns a non- 
inleraciive, non-looping movie iu normal mode when llie 
movie reaches its end. We’ll delve into that issue toward tlie 
end of this article. 


Handling Events for the Fullscreen Window 

Now weVe created a fullscreen window, attached a 
movie and movie controller to iu and positioned the movie 
box so dial the movie appears centered in the fullscTeen 
window. We've also set the movie and movie contrailer 
graphics ports to the fullscreen window' and hidden the 
original movie window. So things are looking greaL We'd also 
like them to start acting great. That is, %ve want the fullscreen 
movie to respond in the normal ways to mouse movements, 
mouse clicks, and key presses, and we w'ant it to jump out of 
fullscreen mode if the user presses the Escape key. 

This Escape key behavior is quite easy to implement. 
Our application framework contains a .stub function 
QTApp_HandleKeyPress that we can use to intercept key 
presses. In QTBigScreen, QTApp_HandleKeyPress is defined 
as shown in Listing 6. As you can see, we look for presses 
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on Llic Escape key while a fullscreen window is active; if we 
find one, we call QTBig^StopFullscreen. 


Listing 6 l Handling key presses 

QlApp_l landleKffv Press 

Roolean OTApp^HandleKeyPress (char theCharCode) 
f 

Boolean IsHandled = false; 

switch (theCharCode) I 

// Escape key during fulJscreen display means to restore the window to its 
original 

// state 

case kEscapeCharCode: 

If CgFijnScreenWindowObject != NULL] 

IsHandled = (QTBJg^StopFullscreen 

(gFullScteenWindowObJeci:) = noErr); 

break; 

] 

return(IsRandled); 

I 


All the other important behaviors we care about are 
provided by the movie controller. So we need to make sure 
that we call MClsPlayerEvent for any events our application 
receives while there is a fullscreen movie. Again we‘11 insert 
some code into another appHcaticm function, 
QTApp^HandleEveni: 

if {(*‘iijyAppOata) .fFunScrecnWltidow != NULL) 

return {MClsPlayerEvent {(**myW] ndowOb jeet) -fControner * 
theBvent)) : 


On the Macintosh, this is pretty much all we need to do 
to make the fullscreen movie behave as expected. Tliat's 
because our Mac framework caJls QTApp_HanclleEvent for 
every event it receives, and it calls QTApp_HandleKeyPress on 
every key event. On Windows, things are a bit trickier* Our 
Windows framework calls these functions only lor MDi cJiild 
movies — that is, windows using the 
QTFram 0 _MovieWndProc window procedure. But the 
fullscreen window is not an MDI child wind<jw. The easy 
soiurion here is to define a custom wdndow procedure for the 
fullscreen window that calls QTApp_HandleEvent and 
QTApp_HandleKeyPress at ihe approiiti^ite limes. (We install 
this window procedure by calling QTMLSetWindowWndProc, 
as you saw in Listing >*) Listing 7 shows our definition of 
QTBig_HandlGM©ssages. 


Listing 7: Handling fuUscreen window messages 

Q'rititLt btidlcM<;ssago 

LRESULT CALLBACK QTfiig. HandleMessaftes (HWND theWnd. 

[ITNT thr'Hc:sf?aec, UTNT wParam, LONG iPfjrani) 

1 


MovieCanlrollei: 

Hovl^ 

WlndovObject 

HSG 

EventRecord 

LONG 

BOOL 


tnyMC “ NULL; 
tnyMovie = NULL; 
niyWindowObject = NULL; 
wyHsg “ lOJ; 
tnyMacEvent : 

myPointji = CeiMespngcPos (); 
□lylstlandlGd = false; 


if (gl'ullScreertWlndowObject = NULL) 
goto bail: 


// mkf sure wt dont (jet oMcxI while the movie is returning to normal state 


if (gKndingFu11 Screen) 
goto bull: 

// get the window ohjeci, movie, and movie controUcr tor this window 
niyWindowObject = gFuIiScreenWindowObject: 
myMG = (* *niyWindowObject). f Control let: 
myMovle “ (**inyWiiifiowObjeet) *fMovie; 

// give the movie controller thi-i message first 
if (royMC 1= NULL) ( 

LONG niyPoititiS GEtHeasagePosO ; 

inyMsg^hwnd “ theWnd: 
myHsg.iDesEage “ theMessage: 
rrtyMeg.wParam = wParam: 
myMsg* TParam = iPatatni 
myMsg,tlliiG * G^tMESSageTimfl0 : 
myMsg.pt.x ^ LOWORD(myPoints); 
myMsg.pt.y ^ lllWORU(myPolTas); 

// Lmnskue a Windows evcjii to a Mae event 
WinEvEntToMacEvont{&myMsg. imyHacEvent): 

// let the application-specific ctxJe have a chance to intercept the event 
mylsRundled “ QTApp_TlandleKventt&myMaeEvent} ; 


siifltcb (thEMessage) I 
case WM CHAR: 

// do any apphcafion-specifie key press liandling 
1 nyTf^Handled = QTApp HandleKsyPress( (char)wPar3Jii) ; 
break; 


bail: 

return (DefWindowPr’oc{theWnd. theHessage, wParam, iParam)): 

I 


'fhere’s nc’)thing too extravagant here* Notice, however, 
that we look at the gEndingFullScreen global variable to see 
whether we got this message during a call to EndFullScreen. 
If so, we don't want to pass the event to the movie controller. 

We need to make a couple of tuher .small changes to get 
everything working satisfaetorily, now that our application 
has to supptnl fullscreen windows. For instance, in the 
function QTFrame_SizeWindowToMovie, we use code like this 
to gel the size of a iiiovie that is associated with a movie 
controller; 

if (jtiyMC !- NULL) 

If EMCGetVlsible(myMC)) 

MCGrtContrnl lerBoundsRect (myMC. &niyRect); 


This assumes that the ctmiroller is attached to the movie, 
which is always true for our movie windows hut false for our 
fullscreen movie. So we need to revise that code like so: 

if (myMC 1“ NULL) 

if (MGGEtVlsiblE(niyMC)) 

t f (MCTjjCnnt r&t lerAttached (uiyMC) 

HCGcLControl1crBoundsRGct{myMC. fimyRect); 


Exiting Fullscreen Mode 

Returning from fullscreen mode to normal windowed 
mode is a breeze, ‘fhe main step is of course to call 
EndFullScreen. To prevent QTB!g_ Hand I ©Messages from being 
called while EndFullScreen is exeaiting, we bnicket our call 
with setting and unsetting the gEndingFullScreen global variable: 

gEndingFullScreen = true: 

myErr = EndFullScreen{(*•myAppBata).fRestoreState< OL); 
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gEndingPullScreefi = false: 


Wc alsu need to restore the settings we saved previously, 
such as the movie and movie controfler graphics ports and 
the visibiliry state of the controller bar. Ir*s n!l pretty much 
wliat yoifd expect (Listing 8). 


Iistin$t 8: Keturning to normal window mcxle 

y't'Hig_SU)pJullscn*cn 

OSErr QTBia„StopFuijscreen (WindqwObject theWlndowObJect} 

< 

ApplicationDataHdl myAppData - MLL; 

OSErr ayErr = paraoiErr; 

If Ubt^WIndowObject ” NULL) 
goto ball: 

myAppData “ (ApplicationDataKdl) 

OTFrarac^GetAppOataFrowtifindowOb feet £thcWindowObj©ct): 

if {myAppOata !“ NllLL) I 

if (C'myAppDataKfFullScr^'finWIndow >= KllLL) I 

// I hi' iirigiiial R Uinjvfi 

(* HheWladowUbject), ft^indov = 

(*‘myAppOata).fOrigWindow: 

MacSet Fort (OTFrame CetPortFronWindowRi^ fe rence ( 

(* * thoW t nriawObJ RCf)* fWindow}J: 

SetMuvioGWoi Id ((* * theWindovObject) ^ fMuvl*?. 

(CCrafFtr) {* ' nyAppData} , tUrigMovieGWorld, 
GetGWoridDevlce( 

(CGrafPtr) t * *PiYAppOata) .fOrlgMovieGWorld)): 
SetMovleBox{(*‘theWlndo^^hject).fHovie. 

&( “BiyAppDara) »fOr IgMovioEect): 

HCSeLCoiU EOllerPof L [ {* * theWifidovUbject) .ICont roller. 

(CGrafPtr)(*‘myAppData),fOrlgMovleGWorld ): 

HC Se t Co n t r o 11 e r At t dc he d ( 

{* *th€WindowGbj€Ct).fConrroller» 
i*•myAppData)^fOrlgControllerArtarhed): 

MCSetVisiblf^{ (' nhpWItidowahject). fConr roller. 

(*'ftyAppUalaJ.rOrigCootto]lerVls): 

HCS t* i Con t ro 11 e T flo urtd a Kec t ( 

(* ^ tfaeWi ndowtlbjec t J. tCont rol 1 er. 

&(* ‘tayAppOata 1, fOrigControllerRect J; 

gEndlngFullScreeti - true; 

1/ fiid f«llS4 itTti pluyback 

cnyRrr * KiidFul I Screen((*'rayAppUaia). fUEeatoreStaie, 

QL): 

gEndingFuJ1Screen = falae: 

// empty out the data strucTurea and global varUblea 
(*’inyAppDataJ . fOrlgWl ndow * NlIliL: 

(*"myAppOata) * fFynScrconltfiridow NULL; 

(■ *rayAppnHtaL fRestoreState - NULL; 

(* *myAppUsta), fOrlgMovieCWorld = NULL: 

gFuilScreenWindowObject ^ NULL: 

ffif END rULLSCREEN AT KOVIE END 

// dispofit' or du* CallMcWlw^n cullbark ^nd Mw ratlliark irPI^ 
if ((•■myAppDataKrGaltBack t- NULL) 

PIspoaeCallBackn * ‘myAppData). fCaltBack): 

if {(“inyAppDataJ.fCailBackUPP !- NULL) 

DispoBeQTCallBackUFPt t**iayAppData) .fCallBackUPf J: 

(--myAppDataJ.fCall Bark = NULL; 
(^'myAppDaMil.rCallBackUPP - NULL; 

lendif 


I 

I 

bait; 

return(myEtrJ: 

}' 

For now, don't worry abotii the code in the 
END,FULLSCREEN_AT^MOVIE^END block; we’ll discuss that 
a hit later. 

Flash Applicaj ion Messai^es 
In a recent article (“T'he Flash”, cited earlier), we learned 
that Flash inovies can send messages to the playback 
upplicaLion requesting that it perfonn specific actions sucli as 
quitting or launching some other application. Of the five 
standard Flash appltcatiati messages, or FSCommands, one is 
relevani to our current concern: fullscreen. This command 
can have one of two arguments, either true or false. If the 
argument is true, then the playback appHcation should put 
the window tainuiining the Flasfi movie into fullscreen mode; 
if it’s false, then the application sliould put the window into 
normal mode. We are now able to upgrade die sample 
application we built in that article. QT FIash, to suppt>rt the 
fullscreen application message. 

QuickTime’s Flash media handler intercepts Flash 
application messages and repackages them into movie controller 
actions of type mcAction Do Script, which are then sent to the 
tipplicalion's movie controller action filter function. In QTFIash, 
we responded to (lurse actions by calling the application 
function QTFIash DoFSCommand. like so: 

case mcActlonDoScript: 

IsHandlgd = QTFIash DoFSCommaridttheKC, 

(QTDciSrriptpTr)ThoFaram^. loyWlndowObject): 

break: 

QTFlash_DoFSCommand. in lurn, inspected tlie command and 
argument fields of the sfiecified QTDoScriptRecord to determine 
which ctmimand to perform. We can now add the lines in Li.sting 
9 to support entering and exiling lullscreen mexJe: 

Lislhig Handling the fultscreen application message 

qri’bsh_tKri^O>mni4na 

if (strcinpCtheScriptPrr >ccHraDaTid. “tuj l£cret5n”) 0) I 
It (sttcsipftheScrtlpiPtr'>arRiJ«<?niE. "true'*) =0) 

QTBig StartFul Jficr^^r [rbeWtndowOb jact ); 

if (strcnip fthaSi^rlpr Ft r >4i ( gywfint i:, ” f.j I Ba") ”0) 
QTB[g„_StopFijl Iijcr at!Ji(tbcWI nduwOhJacl); 

isHandied = true; 

I 

As you can see, we call uur new functions 
QTBig_Slar1Fullscreen and QTBjg_StopFullscreen. Of course 
we also need to add to QTFIash all llie additional c<Hle in 
Q'I'BigScreen that handles lullscreen mode (such as the code 
in QTApp_HandleEvent). 


// m;ikt sure ttn^ mttvkf wIikIow is Uit torretl jd/x and ilicn nIhjw il apln 
QT F r aniens i zeWi nd o^oMov i e t tb eW i nd owOb j ec t); 

OTFrame SetWi ndawVisState (theWindowObject ♦ truci} ; 
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QuickTime Appucation Messages 
Inrerestingly, Quit kTime 5.0.1 intrcKiiicetl a mechi^nism for 
standing rncHsSagL'N from a QuickTime movie Lo Lhe pluyhuck 
appliciilion that is strongly reminiscent of the FSCommand 
capability in Flash iriovies. MTiese QuickTime ctpplicaiion 
messages provide a way for a movie U) request fullscreen mode 
for the window containing the movie, close the window 
containing ihe movie, and perform several other tasks. 

The standard way to .send an application message from 
a QuickTime movie to the playback application is by using 
the kActionSendAppMessage wired action. This action 
recjuires one parameter, which is f>f type long and which 
specifies lhe message to send to the a]>plicatiun. Currently 
QuickTime defines five public application messages (in the 
file Movies.h): 

enam ( 


kQTAppMessageSof twa reCbanged 


= K 

kQTAppHessageWindowClos^Requested 

“ 3 * 


kQTAppHessageExitFullScreenRequested 

“ A. 


kQTAppHessageDlsplayChannels 



kOTAppMessageEnterFulISereenReqnested 

= 6 



I : 

TIk‘ kQTAppMessageSoftwareChanged mcjcsagc indit*ates that some 
[>a[t (jf the QuickTime .s<.jftware hasS l)een u[)dated, and die 
kQTAppMessageDisplayChannels message requests that the 
QuickTime llayer application display its user interface for st^leciing 
one of die QuickTime ciiannels; ncitlicT of these' messages is 
relevant to our samfile applications and we shall blithely ignore 
(hern. The kQTAppMessageEnterFullScreen Requested and 
kQTAppMessageExilFullScreenRequested messages recjuesi liiai the 
playi^ack application put the asscKiated movie window into 
fullscreen or nonnal mode, and the 
kQTAppMessageWindowCloseRequested mes.sage retiuests that the 
playback application close Lhe window' containing the movie. 

We in.serf one of these application messages into a movie 
by inserting a wired action in the standard manner. For 
instance, Listing if) sliows how' we can make a mouse click 
on a .sprite close the movie that contains it. 

Listing 10: Adding a window-close request to a sprite 

tyi’Wi Atit I Wi n< lo wCh wt‘A i'T i<)nTo.Spf iU' 

myP.rr QTTnser t Child (inySpr i U'Ak OJti, ALamlsiCoTnainer. 

kQTHvE?ntType. kQTEventMoueeClickEndTriggerButton . 1. 
Oi NULL, SiiriyEvefitAtom): 
if (rayErr noErr} 
goto bailr 

// iidd un attiem aUUil lo Uh* rwnt Inmlk^r 

myErr ^ QlliissortCl01 d [iiiySpr 1 loAtonu i!iyEv»>ritAtoin, kAetion, 0, 

0, 0 , NULL . itinyActioiiAtaTn) r 
jf (tJiyErr != noKtr) 
goto bail; 

uiyActlon ^ EndianUS2 NtoB(kAct:loTiSendAppM£!ssago) r 
niyErr = QTTnaorrCh i I <! (niySpf i toAtojii, piyAcLloTiAtom, 

kWhicbAct ion. 1. 1. sliseof CioyAc^tion], irmyAction. 

NULL): 

if (toyErr 1^ noErr) 
goto bail; 

// iictd a panimtitT ytom :o fipetif)’ which actitrn to perft^rm 

myNng = EndiaiUB?._NToB(kQTAppMesi;agi>WindowCloat^Rt^4ue3Led3; 

iryKrr " QTTnser iCli i 1 d (mySpri LeAtoin, oiyActionAtOBi. 

kActlonParanieter. 0. 1. sizeof (inyMsg), ^niyMsg. 


NULL); 

We add an event atom whose atom ID is 
kQTEventMouseClickEndTriggerButton to tlie sprite atom 
(mySpriteAtom). Then we in.sert an action atom into that event 
atom. Tlie action atom is given two children, one of type 
kWhJchAction whose atom data is KActionSendAppMessage, 
and one of type kActionParameter whose atom data is 
k QTAp p M essag e Wi n d o wClose R e q u ested. 

Keep in mind that a movie controller cannot handle 
these application messages by itself, 'riie actions requested 
here (entering or exiting fullscreen mode, and closing the 
window containing a movie) require assistance from the 
playback application. Accordingly, the movie controller 
informs the application of the request by sending it a movie 
controller action of type mcActionAppMessageReceived. The 
application is free to act on that request or ignore it entirely. 
In this section, well see how to handle the fullscreen and 
ciose-wintiow applicaiif>n messages. 

Handling Fullscreen Messages 

Ids fairly simple to add support for the 
kOTAppMessageEnlerFullScreenRequested and 

kQTAppMessageExItFull Screen Requested application messages 
10 QTFMgScreen. Listing 11 shows the code we'll add to our 
movie coni roller action Filler procedure to handle the.se 
messages. 

Listing 11; Handling application messages 

qiApp^MCHAcl idJiFilUTPrix' 

case mcActiunAppHessa^GReceived: 
switch ((tang) theParatns) ( 

case kQTAppMessageEnte rFu11Sc reenRequssted: 

QTBig StartFulif?creen(iiiyWtnBow0bj£!Ct 3; 

isR.^ndled trtie: 

break; 

caas kQTAppMessageExiti'uJ lScreenReqyested: 

QTIHg^SLoprul1screen(myWindowObject); 

isllandted ^ true: 

break; 

I 

break; 


Handling Close-Window Messages 

Now' Id’s .see how U) hantlle tlie 
kQTAppMessageWindowCioseRequested application message, Ifs 
tempting perhaps la handle this message by adding these few 
lines of code to the switch .statement in Listing 11: 

case kQTAppHessageWindovCloseRequeEted: 

ClTEraDie^estroyMoviGWinciowt *tttyWlndow0bJect ) .fWindow): 

isHandled ^ true; 

break; 

Here, we simply call the framcwt>rk function 
QTFrame^Destroy Movie Window to close the window 
assoctated with the specifietl movie. This function checks to 
.see whether the movie has been clianged since il was 
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opened or hm saved and, if so, prompts the user to save or 
discard any clianges; once the changes have been saved or 
discarded, QTFrame_De3troyMovieWindow calls 

QTFrame.CloseWindowObject to close die movie file and 
dispose of the movie and movie controller I'hen 
QTFrame^DestroyMovieWindow calls DisposeWtndow (on 
Macintosh systems) or Send Message with the 
WM_MDlDESTROY message (on Windows systems) to 
actually close and destroy the movie window. 

There is a problem with this simple approach, however 
As noted, QTFrame_CloseWindowObject disposes of the movie 
controller associaled with die movie, and experience tells me 
that this is definitely a had thing to do inside of a movie 
cimtrollef action filter procedure. So we need to adopt a 
different approat'h: in response to the 

kQTAppMessageWindowCloseRequested message, well set a 
flag in our application data record that indicates iliat we 
need to destroy the window object. Listing 12 show's the 
code well add. 


Listing 12; Handling close-window messages 

QTA pp_MC Act itmfiJlf rProc 

case kQTAppMessageWindowCLoseKequeijted; 
inyAppDat.a ^ (ApplicationDataHdi) 

QTF raiHP_GetAppDataFroffiWindawOb j ect (myWindowUL j ec L) : 
if (niyAppData !“ NIJI>L) 

(* *iiyA[}p[lata),fDc^rroyWindowNeeded = true; 
isHandied = true; 
break: 

Liter, in the QTApp_HandleEvent function, well need to 
cycle through all open movie windows to see whether any of 
them needs to Ix^ closed. We’ll add a while loop, as shown in 
Lusting 13, 

Listing 13: Looking for windows to close 

QTApp^UaaiUcl-vLTit 

tnyWiadow = QTFraiiie._GptFrontMGviaUindow (); 
while (niyWiadow SULF.) I 

inyNextWindtJW ^ QTFramLuGotNcxtMovieWiiidDvtfflyWiiidDw) : 

rnyAppData = (AppiicationDatalldl) 

QTFrame GatAppDataFconiWindow(iiiyWind*>w); 
if [itiyAppData != NULL) t 

if [('•myAppData),fDeetroyWindowNaeded) t 
t'‘niyAppDiita). fOfifitroyWindowNeeded = false: 
QTi:‘raine_DestroyMov i eWi ndciw(rayWindow) ; 

I 

1 

myWindow = myNextWindow: 

I 
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looks (or litid intcrprcls this user ikm iiem, and in this section 
well see how to handle it in QTBigScrecn (at least in pan)- 
'llie data contained in a ptv ' user data item occupies 8 
hytes’ we can exhibit the stmeture of this data using a 
QTPFSDataRec structure, defined like tliis: 

typedef struct \ 

UTntlfi 

UTin 16 fUnuscdl; 

llltitl6 fUTiused2; 

liooleai] fPlaySlidcShow^ 

Botjlean fPlayOnOpeni 

I QTPFSDataRec: 

This Structure is defined in our file QTBigScreen.h; ihere is no 
"ptv * item structure defined in any of the public QuickTime 
header files, (By the way, “ptv" stands for "print to video"; 
this is because the presenting capalnlhy was inlentied also to 
provide a non-windowed version of a movie that could be 
wriilen oiil to videotape,) 

The (Size field contains a l6-btt integer that specifies the 
desired size of the presented movie. The value 0 indicates 
ihat the movie should be presented at its ntmiial size. The 
value 1 indicates ihai the movie should be presented at iw'ice 
its normal size. The value 2 indicates that the movie shouUI 
l>e presented at half its normal size. The value 3 indicates 
that the movie shoultl be presented fullscreen. QuickTime 
Player calls BeginFullScreen with the appropriate width and 
height to present the movie. As weVc seen, however, this 
can cause the resolution of the screen to be changed, in 
whicli case the aciual size of the presented movie might not 
he what we would expect, 1b force Qiiick l ime Player to 
present the movie at its normal size, we can specify the valtje 
A. Well define these constants for the fSize field: 


CFivttn I 

kSl^eHormal ^ 0. 

kSixeOoubie 1, 

kSl^eHair - Z. 

kSlzcFullScr«>cn = 1, 

kSizeCurrent - 4 

I: 


Tlie values of tliese constants appear to derive from the order 
of the items in the Movie Size pop-up menu in the dialtjg box 
displayed by QuickTime Player wiien the user selects the 
""Present Movie.,." iiern in the Movie menu (shown in Figure 
3b 



figure J: QuickTime Player's Present Maine dialog box 


The fPlaySlideShow field contains a Botjlcan value I hat 
indic^ates whether the movie should be played in slide-show 
mode; in slide-show mode, the movie advances to another 
frame only wlien the user pre,sscs ihe righl-arrow or left- 
arrow^ key (which move the movie forward one frame or 
backward one frame, respectively). Any .sounds tracks in the 
movie are ignored during slide-show mode. Finally, the 
fPlayOnOpen field contains a Uinjlcim value tliai indicates 
whelhef the movie should begin playing aiilomaiically when 
the movie is presented. 

listing 14 defines a function that we can use to add a ptv 
' user data item to a movie. 


Listing 14: Adding a pJay-liillscrcen Item to a movie 

Q’ntilC,Atk!FTVlirni'roMtiviL- 

iJciPfine kPTVTtcnType FOUR.ClIAK.CODBClitV ’) 

OSBrt QTBls_AddmiteiiiToHovie (Movie theHovle) 

I 

UserData myUsErData “ NULL; 

shori myCoimt “ 0: 

QTPFSDataRoc myPFSDnta: 

OSErr tnyErr ^ titjErr: 

// ttic mnm' S usLy tkiti WjA 

myaserData = CetHovieOgetData(theMovie): 

If (inyUserData -= NULL) 
return (parantErr): 

// wr want lo end up with at mm t/nr ustT ttaia item nf lyp^ ptv*, 

// sn lei's any existing ones 

myCfjiint * CnuEitU3t.vrl3titytype{fflyU^serData. kPTVltemType) : 
will If* (tnyCoutiL J 

Rf?nnjveUijetData{myUserData, kPTVItemType, 1): 

// add a new user data item of type ptv ‘ 

myPFSData.fSize = EndianlJlfuNtoBtkS I kc»Fu 1 I Screen}: 
rayPFSData*fUnuGP.dl " 0: 
tnyPrSData. ftFnunnd? " 0* 
tny PFSDat a. rP lay slideshow ^ falue: 
myPFSData.fPlayOnOpen true: 
myErr = SetUserDatalteinCmytfetrData, 6iityPFMData, 
sizeof(iiiyPFSData}. kPTVIteiaTypp. 0): 

return(ayErr): 

I 

QTBig_AddPTVltemToMovie adds to the specified movie a ptv 
" user data item that requests that ihe movie be played tnick 
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fullscreen and ihat the movie sian playing as soon as it's 
opened, (It's worth mentioning that a movie can also 
contain a user data item of type ptvc', whose data is an 
RGBColor stmaure that specifies the background color of a 
presented movie.) 

Now, when QTBigScrecn opens a movie file that 
contains a movie user data item of type ptv ' and liie value 
in the fSize field is kSizeFullScreen, we want to call our 
function QTBig_SlaHFullscreen to play it fullscreen. We also 
want to inspect the fPlayOnOpen field to see whether the 
movie should begin playing immediately. Well add the lines 
of ci>dc in Listing 15 to our framework function 
QTFrame^OpenMovielnWjndow, 


Listing 15: Proee-ssLiig a '^ptv ’ user data item 

QTFmme^t JjKuMuvii: I n Winik>w 

U^erDota ayUserDaca ^ HULL: 

QTPFSDataRec myRec: 

OSErr tnyErr ^ paramErt; 


// get the UNtT <hu last 

inyUserData * {k*tHovl€*lIfjerllaTa{iiyHovic); 

if (ifiytlserDflta t- HULL) t 

myErr GeiUaorDataltetattByUaerData. StnyRec, slzeot(myRec). 

FOUR_CHAit_C;Ul>Et*ptv ')» 0): 
if (ii^yErr “ noErr) ( 

myRec, fSise ■ Endianillti, BtoN(myRec . fSiste): 


if (myRec.fSl7e ™ kSizcFullScreen) 

MCDoActlonCmyMC* tncActionAppHes^ageReceived. 

{void MkQTAppMessageEnterFullScreenKe^itjested): 


\ 


if tmyRec,fPlayOnOpen) 

MCDoActlcn twyHC. mcActionPretoHAndFlay , 

(void ')tJn^rMovicPrererfedfiaLe[«iyRovie)): 


Notice that we don't call QTBig.StartFullscreen directly; 
instead, we issue a movie controller action of type 
mcActionAppMessageReceived with the parameter 
kOTAppMessageEnterFullScreenRequested. winch (as we've 
seen) causes QTBigSc'reen to call QTBig^StartFullscreen, 
Notice a 1st) that we ignore all size values except 
kSizeFullScreen; l1l leave it as an exerci,se for the motivated 
reader to modify QTBigSereen so that it can present a movie 
in any of the currently defined ,sizes. 


calling the GetMovieTimeBase function. We can aiiach to a 
time base one or more callback functions iliat are triggered 
when a specific callback event occurs. Currently, five types 
of calll>ack events are defined; we intiicaie a specific type of 
callback event using these constants: 


fiTlUOl 1 

call BaekAtTtrat'* U 

callEackAtRaie * 2, 

callBackAtTimeJump = 3, 

callBackAtExtremes “ h* 

callBackAtTiiiieBaseBlEpoEed ^ 5 

h 


'I he callBackAtTime event causes a callback function to 
he called when a specific time value in the movie is reached 
(for instance, when the movie reaches the 2 second mark). 
The callBackAtRate event causes a callback function to he 
called when the movie begins to play at a specified rate (for 
instance, W'hen the movie U played at twice the normal 
s|>eed). The caSIBackAtTlmeJump event causes a callback 
function to be called when a jiinifi in lime occurs; lliis means 
that the callback function is calletl whenever the movie time 
is SCI to a lime different from what it would be set to under 
normal movie playback (for instance, if the user dicks in the 
movie controller bar to ,selecl a different movie time, or if a 
wired action changes die curreni movie lime). I'he 
callBackAtTimeBaseDisposed eveni causes u callback function 
to be called when the time l>ase i,s about to be disposed. 

For present purposes, we are interested in the 
callBackAtExtremes event, which occurs at either the 
beginning or ihe end of the movie. As we'll see in a rnomeni, 
we indicate that w'e want our callback limction to be called 
at the end of the movie by passing a specific value when we 
activate the lime base calll>ack. 

In QTBigSereen, we call the QTBig_lnstallCallBack 
function to install a lime ha,se callback function to return 
from fullscreen mode to norma! mode at the end of the 
movie. We add these lines of coile to QTBig_StartFullscreen: 

Km FULLSCREEH^At MnVTr_KNn 
// ii catlly^'k prtx'ediitT ki return liiu'iir, nf>n-li>nping ninvies 

// tn iiurnuii nmde ni Ihr end at !he rmyvie 
if (QTBlgJtoviei^iStoppabletinyMC)) 

QTBig_iTiEtaItCallBack(tlieWindQwObject): 

#endil; 


Time Ha.se Callback Functions 

We noted earlier that QuickTime Player aulomalically 
returns from fullscreen mode to normal tmule when it 
reache.s the end of a non-interactive, nondooped mtwie. We 
can adiieve ihis same behavior in QTBigSereen by installing 
a time hose callback fttnclkm, a function that i,s executed 
when a specific lime in a movie is reached or when some 
other event related to the movie's time base occurs. 

You may recall from previous articles that a movie's lime 
base controls the direction and speed of movie playback, as 
well as its looping state and current movie time. A lime i>ase 
(of type TlmeBase) is aiiiomatically created when we load a 
movie; we can retrieve a movie's Lime base at any time by 


The definition of QTBig^MovielsStoppable is tpiite simple; 
we just call MCGetControllerlnfo to deieniiine w'lielher the 
movie is looping or interaciive, as showm in Listing 16. 


Listing l6: Determining whether a movie should be 
slopped 

Q'rUiiC Mavit USu jppul jIc 

Boolean (JTEi^Moviet&Stoppable (MnvleCom:roller theMC) 

! 

long ayFlags - OL; 

MCGetControllerlnfoCtheHC* ; 

if ((myFlagei & racInrolBLooping) |1 

(rayFiagB & meInf oHovle IsInteractive)) 
teturnCfalfie); 
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else 

return(true); 

J 

Ncm wc need lo insiall a time l)afie calll^aek funetion 
and respond when rhe callback function is triggered. 

Installing a Time Ease Callback Function 

To install a time base callback function, we create a itme 
base callback and then activate it. We create a time base 
callback by calling the NewCallBack function, like this: 

myCaliBack = NewCallBack{ 

GetHovieTiineBase ((* •theWindowOb ject). IHovie] » 
callBackAtExtremes): 

As you can see, the first parameter here is the movie’s lime 
base, and the second parameter is a constant that indicates 
the kind of callback we wish to c:reate. We can set one or lx>th of 
the two liigh-oixJcr l)iLs in ilie second parameter to retfuesi liiat 
our callback function can l^ called at interrupt time or at deferred 
task time, using these constants: 

enuin [ 

callBackAtlntetnipt = 0x8000. 

callBackAtD^ferredTask = 0x4000 

f: 

Setting tliese bits results in more accurate timing, but the 
callBackAtlntermpt flag lequires that the callback function lx? 
interrupt-safe (in panicular, that it not cause any memory to be 
allocated or moved). We don't need extremely ateeirate liming in 
returning the nxwie from fullscreen to nonnal nuxle, so well 
leave these liits clear when we call NewCallBack. 

To activate a lime base callback functifrn, we call the 
CallMeWhen function, which is declared esseniially like this: 

OSEtL CallMeWhen (QTCallBack cb, ftTCa]1BacktlPP railBackProc, 
long refCon, long parainK long para(ti2. long patain3): 

Here, cb is the callback we created by calling NewCallBack. and 
callBackProc is a universal prcx’edure |X)inrer for the callback 
function. The refCon parameter is a reference constant that is 
passer! to the callback function; as you might have guessed, we'll 
pass rhe window object for the fullscreen window as the refCon 
parameter. The last three parameters lo CallMeWhen coniain 
additional information required for the callback and vary 
depeixiing on rhe type of rhe callback. For a callback of type 
callBackAtExtremes, only the parami parameter is used; it indicates 
which movie extreme we want to taiget. We can use iliese 
constants to specify a movie extreme: 

enuin I 

triggerAtStart ^ OxOOOi. 

triggerAtStop = 0x0002 

h 

In QTliigScreen, we want to keep track of ihe callback and 
the callback UFP, Accordingly, we'll add a couple of fields to the 
applic'aiion data rec'ord (defined in the file ComApplication.h): 

QTCallBuck fCallBack: 

QTCallBackUPF fCailBackUPF: 


Finally we can give tlie definition of the QTBiq.lnstallCallBack 
hinrtion (Listing 17), It calls NewCallBack and CallMeWhen, and it 
stores the callback ideniiller and the callback IJPP in the 
application data record. 


listing 17; Installijig a time base calE^ck hinctian 

QTRifL.ln.'itallC.iilUkk’k 

vaid QTBig^IriiitallCaUBack (WiiidowObjecl theWiridpwObjecl) 

I 

AppiicationDataHdl myAppData ^ NULL: 

QTCallBack myCaliBack ‘ NULL: 

if [th^WIndowObjer.t = Nm*L) 
rcTuro: 

If ((1 " theWindowCbject) . fHovie = NULL) 
return: 

niyAppData “ (AppiicationOataHdl) 

QTF ratitfi_Ge t Ap pB a t F rnmW i nd awOb j ec t (th eW ind avOb jeer): 

if (uiyAppData = NULL) 
return; 

myCaliBack ^ NewCallBack( 

GetHovieTimeBasel (*'TheWindowObiect)^fMovie), 
CallBackAtExtremes): 

if (tnyCallBack != NULL) [ 

{* * myAppDa rn),fCa11 Back = myCa11 Back; 
t *' my Applla i a), f Ca ] 1 Bac kU F F = 

NewQTCa i 1 Bac kU PF ( tlTB i g_l* u 11 sc r eenCa 1 iBack ): 

CallMeWhen (myCaliBack, (“myAppData). fCallBackUPP . 

(long)theWlndowObject, triggerAtStop, 0, 0): 
i 
I 


Handling a Time Base Callback 

Now our callback is primed and ready to fire when the movie 
reaches its end, Al that point, the function 
QTBig_FullscreenCallBack is executed. QTBig_FullscreenCallBack is 
declared like this: 

PASCAL_RTN vo i d GTBI g_FiJ 1 ] ac reenCa 1 ) Back 

(QTCaltBack theCallHack. long thekefCon): 


'fhe first [Xinuiieter is the callback identifier; tiie second parameter 
is the reference constant we passed to CallMeWhen, which is of 
course ihe window object for ihc fullscTcen window. In general, 
it’s best to keep callback functions shon and sweet; the 
recommended practice is simply to set some flag that is inspected 
elsewhere in ihe appliciiiion. Listing 18 gives our definition of 
QTBig FuliscreenCallBach. 

listing 18; Handling a lime base eallhack _ 

QTBig_F»Iiscrtt‘nCailBa<k 

PASCAL_KTN void OTBlg.bulli5cre4?i\Ga 11 Bark 

(QTCallBack theCallBack. long theRefCon) 

1 

WindovObject layWiudowObject ^ 

(WlndowObject)theRefCon: 

ApplIcat ionDataHd t myAppUata ^ NtiLTi; 

QTCallBack ray Cal IBack NULL: 

if (myWindowObject =■ NULL) 
return: 

inyAppData (AppllcationDataUdl) 

QTFrarae_GetAppUataFroraWindowObject(rnyWindowObJecr): 
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If (myAppDatfl ” NULL) 
tet urn; 

if ((* *fflyAppDuia} . rCiillH^ick 1= thcCallHack) 
return: 

// lundc ihlv wjnd<»w for ending fyllHTrt'n nuHJr 
(*’niyAppData)»fEndFuI IsereenNeeded = true: 

U rlcan iip the rallhark siuff 

if E {* ^myAppUau* J , rCa 11 Back !” Nlfl/L) 

Dispo^eCaimack ((* *iiyAppData] . fCal! Buck) : 

if £C'myAppData).fCallBackUPP f- NULL} 

DispnneQTCallBackUPP((*’myAppData).fCalIBackUPP): 

(* *iiiyAppI)ata} . fCal I Brick - NULL: 

("‘iiiyAppliijLuJ . rCal 1 BfickllPP - NULL; 

I 

Hirst, wu cast ihc theRefCon parameter ta be <if type 
WindowObject and make sure that we are given a non-NULL 
window ohjeti. Then we extract the apfiiication data 
usKodated with tliat window objecr and verify that the 
callback passed to the callback function (theCailBack) is the 
same as the callback stored in the atiplieaiion data record 
((**myAppData)JCallBack). If everything checks out okay, we 
set the fEndFullscreenNeeded field to true. Well add some 
code to the QTApp^HandleEvenl fund ion that t flecks iliis 
field anti returns a windtw to nonnal mode if it is true. 
Remember that we already go looking for any windows that 
are marked for returning to nt>rmal mode, so we can rework 
the while loop as shown in Listing 19 . 


Listing 19: Looking for windows to return to normal 
mode _ 

QTApp HiindtcEvcnt 

myWiudow - QTFramc^GtnFrontieWinaowO : 
while tmyWindow f= NULL) I 

lay N^xtWindow = QTFrai!ie_C4°t Next MovleWiiidow (my Window]: 

myAppData “ (ApplicationDataHdl) 

QTFraae G^tAppDataFromUindowCQiyWindow); 
ir (inyAppDara 1- NULL) I 

if ( (‘‘myAppLVa La) . f LndFu11 acreenNncdrd) [ 

E**BjyAppData) . fFridPullscreonNeeded ” false; 
QTBig_StopFullscreeri [ 

QTFcaiiie_G^tWlndowObjeett'rDtnWindow(myWindow)) : 

I 

If ((*‘myAppDatfl).fDRKtroyWindowNeeded) \ 

£ *'myAppOala) . TDcfit royWi hdowNf*f!d*>d = 

QTFram^_U<?si royMovicW i adow(aiyW i ndciw); 

] 

I 

myWindtiw myNexrWindow: 

I 

Finally, since we are done with the callback, we call 
DisposeCallBack to dispose of the callback and 
DisposeQTCallBackUPP to dispose oi the calU)ack UPP. We 
finisli up l>y clearing out the fields in the application data 
rectird tliat store the calll>ack and callback LJPP. 

CONCLlfSlOPJ 

LeLs quickly recap what weVe learned here. A mtwie 
can contain a movie user data item of type ptv ' lliat (usually) 
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PROGRAMMER'S 

CHALLENGE 


hy Hoh liinnisim, Westford, MA 


Disk Dei ragmentation 

CX'casionally fx^ople write me to say tlial the 
Cliallengus in ill is coluiun are loo clifFit nil, iliai ihere just 
isn't enough lime to solve the problems in the two plus 
weeks before the solutions are due. And in looking' 
back^ I iiave to ion less ihal the problems fiave gotten 
more difficull over lime, I lediscxjver this trend irom 
tinie to time, and IVe made several attempts to reverse 
il, «)nly to have the problem diffieulty creep up again 
after a while. Or, us others liave written, I lake a 
reasonalile problem and pul stjnie evil twist into ilie 
problem stalemenl, making it impossible- In part, the 
increased difficLilly is because all of the easy problems 
have already been solved. Like all of the inventitxns 
worth inventing have been invented, and discoveries 
worth discovering have l>een disctxvered, and dtK'toral 
theses worth writing have Ixeeii wriUen, Prol>al)ly not 
true, it jiLSt takes creativity. So this month we'll make 
ancjther attempt at a simpler problem. In the future, of 
course, you readers can helfi f>y sending in your 
suggestions, whicli not only gives you the saiisfaclion of 
suggesting a tlhallenge that can actually be solved in I lie 
time available, ytju earn iw<x invaluable Frograriuner's 
Challenge points if we u.se your suggestion. 

11iis monilds Cdiailenge? Defragment a simulated 
disk drive. Kor each lest case, you are given a ili.sk 
drive with up Ui 52767 (2AI5 I> block.s. On that drive 
are a number of file.s, some allocated contiguously, 
some allocated in a number of nuncontiguou.s 
fragments. Your job is to move block.s of data so that 
the stonige h>r each file is contigutxus. li doesn t malt it 
where on the disk tite files aie located; tlie free siorage 
remaining on llie disk tloes not neial t<) be coniiguous. 
Ihere is one ccmsliaim - the amount ol available 
auxiliary siorage is limited, stj you cannot remove 
multiple l>k>cks of data from the disk to make room lor 
others. You can move a contiguous secpience of disk 
[docks from one locaticjn to aiKJilter in a single 
oj)eraiton, as long as they don t overla]> 

Tile file defrag.in ta>ntains a single line witli the 
number of lest cases your program needs to process. 
The input for each lest case is fuovided in file 
defragNN Jn, where NN ranges from I to tlie number of 
test cases. I'he first line of this input file contains the 
number of blocks in the simulated disk to Ih* 
defragmentecL I'he next line contains the number of 
data files cxn iliai disk. The remainder oldhe input file 
is a .setfuence uf lines for each data file. The firsi lini^ 
for each data file is the number of fragments in the 


allocation of the data file on the disk. Tliis is followed 
by a line for each fragment, containing the disk block 
where the fragmetit sraris, and then the number of 
[docks in iliai fragment. So an input file might look like 
the following: 

32767 number of blocks in the Blmulated di.^k 

iO - number of files Iri this ten I ciifio 

i number of frfigm^nis for ttic fitsi file 

112^4,100 frygi»R.MU alar is £it block 11234, uses 100 blocks 
3 number oJ ftag^ieiLlS tor the second file 

0 334,10 fragment slarte at block J 1334, uses 10 blocks 

1U34,100 - fragment starts at block 1104, uses lOO blocks 

11344,50 fragment starts at block U344, uses 50 blocks 

_ continue for iJ more files 

V'our program should ptficess each input file and 
output a setjuence of block moves to die file 
defragNN.out. Hacli block move should produce one 
line of oulpui with 5 numbers: 

fi f alBlockToMove. newBiockLocat ion, nuinberOfBlockstoHoi/e 

lunally, your program should produce a 
challenge.log file, with one line per tesl case containing 
llie iiittrger number micrtxseconds used by your 
applicathxn lo .solve I ha I test case, including the time ti> 
reatl the input, find the .solution, and produce the 
output file, 'rhe methotl irsed to measure execution 
lime may vary based on the rievelopment environment 
you use lor your solution, but you sliould measure lime 
with niicn>seci)nd precision if [>ossil>le. 

You can improve your chances of winning hy 
incorporating opiitinal features into your solution. For 
this disk defrag men la t it m [>roblem, you luiglil W'anl U> 
tiptionaliy display ytjiir stdution's j^rogre.ss in 
defragmeniing the disk. 

Scoring will be based on minindzing the number of 
move sequences retjuiied lt> delVaginenl llie disk, on 
minimizing execution time, on a subjective evaluation 
tj|‘ additional features, and on the elegance of your 
ctide, inc I titling the commentary that describes yt>ur 
solution. Your base sctire will be l(K) penally points Ibr 
each defragment move seciuenct'. You incur the same 
niimlier tif penalty ptjitUs for a move of t)ne bUxk as 
you incur for a single mtxve t>f multiple contiguous 
blocks. For each test case, your penalty points are 
iiureased by 1% per nullisecond of execution time. 
Your penalty points will be decreased by up lo 2S% 
liaserl on any optional features you might incorporate 
into your solution, aiul l>y another 25% based on a 
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Kuhjct liVL^ evsiliunioii ui' the elegance of your .solution. 
Since one of I lie reasons people read the Challenge 
column is to learn fecliniqiies from otir ChalU.UTge 
masters, it is impcirtant that your code !>e well 
docLimented. Code clarity and commentary will be 
considered in tlie ewalualion of elegance. 

d'his will he a native PowerPC Challenge, using the 
devekjpment environ ment of your choice, jn ovrded I 
have or can obtain i\ copy — email 
progchallenge®mactech.cotn to c heck before you start. 
You c'an deveh)p for Mac OS 9 or Mac OS X. Your 
sokilion should be a complete Macintosh application, 
and your sutimission should provide everything 
needed to l>tuld your applit'ation. 

A tjuestion for you readers, especially those of you 
that iiave entered or plan to enter the Cliallenge: how 
many of yent use Mac OS X regularly? As I write ill is, 
Mac OS X has been around for a year or so, and for 
pcrliaps tiaif that time in a iisealile form. I'll confess, 

I ve stuck with Mac OS 9.x until recently, but l‘ve Mi 
my most reccait rnacliine in its default ccmfiguratioii, 
booling into Mac OS X 10. L AlthtRigh it sUll annoys 
the heck out t)rme on occasion, it is beginning lo grow 
on me. Are we ready to move the Challenge to OS X 
exclusively? Let me know^ wliai you think, 

Winner of the January^ 2002 CHALi.KNtiE 

Thv [amiary Challenge rtxjuired contcsiams lo 
write a player for TriMinesweeper, a variant on the 
traditional MineSweeper game. Like the classic’ 
Minesweeper, this game rec|uires one to map out an 
arrangement of cells, discovering which cells are safe 
and which contain i>ombs. Moves are made by 
querying one cel) al a lime, designating whether tliai 
c^ell is believed to be empty (safe) or to contain a bomb 
(unsafe). Util ike the classic game, cells in 
IriMineSweeper are triangular in shape, and eacii cell 
has twelve neighbors instead of eight. 

Congratulations to Xan Gregg for winning the 
IriMineSweeper Challenge. Xan wa.s .significantly more 
successful lhan (Ulier contestants in sedving the 
'lYiMineSweeper l>oatds, succeeding in solving eight of 
the ten test cases I used in the final evaluation. Mis 
solution al.so used less execution time lhan either of 
the other loj) two contestants. His strategy was to make 
all obviously safe moves, then to evaluate the 
collective information about the remaining cells to 
deduce and make tjiher safe moves, and then to "pray" 
and gues.s a eell, favoring those cells that have a lower 
chance of containing u bomb based on what is known 
from neighlioring cells. 1 suspect tiie reason Xun's 
solution was so successful lias to do with the w'ay he 
managed "sets”, or collections of unknown c'ells 
surrounding a given cell. By combining infonnaliun 
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from c^verly^pping .sets, and by doin^ so during a "clean 
up” pass rather tluin after each move, Xan identified 
new safe moves and did so efficiently. 

The second’place solution by Ernst Munter also used 
the concept of sets of cells surrounding a given cell, but 
apparently derived less information from overlapping 
sets, causing it to have to guess more frequently. Ernst's 
solution was designed in sucfi a way that it could l)e 
adapted relatively easily to other board topologies. 

The boards in the evaluation test cases ranged in 
size from 20x20 to 100x100, willi ihc percentage of 
ceils occupied by bombs ranging from 2.5% to 10%. 
Half of the test cases had 10% of the cells occupied by 
bomlis, and half liad fewer. 

The table below lists, for each of tlie solutions 
submitted, the total execution rime in milliseconds, the 
number of points earned, equal u> the sum of the 
number of board cells in each game successfully 
solved, minus one point for each millisecond of 
execution time. It also lists the code side, data size, 
and progratnniing language used for each entry. As 
usual, the number in parentheses after the entrant’s 
name is the total number of Challenge points earned in 
all C^hallenges prior to this one. 

One last note. I received an entry coded in BASIC, 
but was unfortunately unable to evaluate it because 
this Challenge required an interface to a test driver 
written in C. BASIC fans, and users of other 
development environments, are encouraged to enter 
this month's Challenge, where solutions are stand- 
alone apf>li cat ions. 
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Mftiil liASIt: 


Rank 

Name 

Pointf 

wins 

Total 



(24 iiiul 

(24 mo] 

l^>ints 

1. 

Munter. Ernst 

27S 

to 

852 

2. 

Rit-kon. WillL'kc 

66 

3 

154 

5 

Sit.'ilon, liMii 

52 

1 

210 

1. 

Willi Cbes 

49 

2 

49 

5. 

T:3ylorJon:nh:m 

39 

3 

6.5 

8. 

tiregg, Xan 

20 

1 

110 

9. 

Malldijwfr 

20 

1 

114 

10. 

CxHiper, Tony 

20 

i 

20 

U. 

Tniskicjr, Peier 

20 

] 

20 


AEVD THE Top COISTTESTANTS lOOlONG FOR A ReCENT WlN 
In order to give some recognition to other participants in 
the Challenge, we also list the high scores for contestants 
who have accumulated points without taking first place in a 
Challenge {luring the past two years. Listed here are all of 
those contestants wlio liave acx uinulaied 6 or more puini.s 
during the past two years. 


Rank 

Name 

l\)ints 

Total 



(24 mo) 

Points 

(i, 

Lktrinjt, ItaiKly 

28 

144 

7, 

Sadet.sky, 

22 

24 

12. 

SEen>;t'f. Allen 

19 

84 

J3. 

Shearuf. 16 if* 

19 

62 

14, 

SdiiriiiiiKin. Jan 

16 

16 

15, 

Man. Alan 

14 

59 

16, 

Maurer Selra^stian 

11 

308 

17. 

Nep.su e>l3. Konalcl 

10 

S7 

IH, 

t>4y, Mark 

10 

511 

Vk 

IX'sk’Ik Nidj 

30 

JO 

2(3. 

Mi kins 

to 

30 

23. 

RiiwrrN, Sue 

10 

to 

IL 

k?!lincr. Will 

- 

7 

25. 

Miller. Mike 

7 

7 


There are three ways to earn points: (1) scoring in the top 
^ of any Challenge, (2) being the first person to find a l)ug in a 
published winning solution tir, (3) being the first person to 
suggc.si a Challenge that 1 use. The points you can win are: 


Top Contestants * 

Listed here are the 1'op Coniesianis for the Prograininer’s 
Challenge, including everytme who has accuniulaled 20 or more 
points during the past two years. The numbers l>elow include 
fx)inls awarded over ihe 24 mt>si recent nintests, inchKiing 
points earned by this inonilCs entrants. 


1st place 

20 points 

2nd place 

10 points 

3rd place 

7 p{)inl.s 

4th place 

4 f>oinls 

5th place 

2 points 

finding hug 

2 points 

suggesting Challenge 

2 points 


64 


MAdTECH • Ami 2002 











































Collaborative Coaimerce 


afillfor People^ tOO 

. V'...V. ... * ^ - .... 








0i.Ap|)yjCiA »ni( lavMyHcKsks ore rci;isi<3fcii imdemarks of Apngc*! Basiiic® SoRwiiiCh loe iWMiancydanPc is s rcsisrcn:ijl tr^dcmsik of Afip(jca Peritonal Soft wore* 1.1.f.‘. 
Linux is a ifadennark of iJaiw Torvnld-i, ^/Wimlows k i regisKifcd traikmaric of Miciuwifl Lurponitinn. 









Here m Xan s winning I riMineSweeper fiolution: 

Jan02 Solutions’ 

Copyriglit © 2002 
Xaii Gregg 

/* JHjIuiion to trimtiicSwt'qKT t^jgrammtT s CiuUcngiL- 
irLiri{;ular mint: swcqMfr piuidtfs. 

Kt^trps liiil »f sctH (jf crib. Eadj scl aimrsptiiHb lo ihe nnkrwiwn cells sLirrxmmlinj^ y 
given cell; then: is a maxiniuiti tjf 12 ccib per set. Eadi set ulstj knows its ttjtal tM)mh 
count. 

Kjich cell in ihe st'l is n^priisented by Us hoard Index, that is, rtiw * htJatxLSiM' + col, 
Memlx’r cells an* siotnl in ntimerieni tjriler to spetxl seaa'heji for eelb and set 
eompariMin, 

Villen a non-httnih cell is revealeil.a set b added with the learned inftinriaiion. 

The play rtHTSily eiinsists of n^peatedly ntakioR safe moves tintil there are none. 

"Safe" moves art* n'sxiUing cells in st'ts whm* the Iximb ixnmt is wro or the homh 
cotmt Is the same as iltt' menilXT count. 

WItcit no safe moves are ohviotLsahe sets are jiroressed to remove ktiown celb and 
elimUtaie subsets Rentoving the known cells as iltcy are discovered turns tmt to be 
quite a bit slower than doing it Ui the eleamup jrxsii. Por subset elimlnatiofi, sets iltai 
an* HulMi'ts of other sets aa* a'duent so that 

kelb 2bomhs(U,l2)(li,15)(llj4)(H,15) 

,kcUs Utomhs (n, 12) (I i, 13) (H,H) 

gets reduced to 
1 cells ihombslM JS) 

Veils thomlw 11 L12) 11IJ3) (11.N> 

which prtHfiiecs a s;ile move for the* next move pass. When llutt fails, the prugnmi 
will khjk for eeriain iiUersc'eting seas, stich as 

(redls 'dxmil>s(l<)J2)(lLI2)(II.13)(iia4)(ll,l^)(HJ<v) 

4cell.s Ihomlw ( y, 12) {n , 12>( n ,15) { IU4) 

which will poKlnce 

Veils 3hombs fid, 12) f M,H) {11.16) 

IceMs tH>onilTscy,12) 

Veils lfwmi!xifllJ2)ill.l3><nj4) 

when the common sul^-t b factored out. Si*ems to come tip in about J in UKH) 
gantes,so the ^-alue here is debatable. 

When no safe moves or set rt'diKtious aa* possiltle then the only optitm is urptay" 
and rt'veal a ramlom square. t>f course, (iiayer b RXjuired a I Vast for the ftrsi few 
moves. Ik'fore gue\sitig, sets ate compared to determined the safest guess band tin 
lx mil IS i wr nietiiU r. 

7 

Ifinelude “Tr imJneawfteppr.h** 

if Inc hide <«tillo.h> 

#Include <sidllh,h> 

#iucludp <ffacMeiiiory,h> 

static canst char *fthoard: 

static int gBoardSizei 

static int gEombrtRf'inaiiHngj 

ft r.a r 1 r ! ri r gfin knowtiRoina I n i n g r 

srat le MlricHweeperMoveProc gHakeHove* 

static int gMaxUpl!: 
static Buolean gtlaiieOver: 

// arguments Itir MakeMove (unaion 
Adeline kCheCk false 
j^definp kHarkBowb true 

// iIh- mam data stnn tuR': a st'i of cells 
#cicflne kHaxMeighbnrs 12 
typedef struct Set I 
int nesiberCount; 
int banbCount: 
int numbersIkHaxNeighhorsJ: 

I Sot: 


// the list of sets, alkwated si/c grows as needed 
static int gSatCount; 
static int gSatAlloc: 
static Handle gSetHandlej 
static Set ‘gSets; 

// Jisi of sets that have been touched. 

// and thus may need ckraoir^ 

// iixed size is OK because it s ok if everyUtihg can t be recorded 

^define kStackSize 1000 

static int gTouchedStaek[kStackSizej: 

Static int ^TouchedCount: 

// utilities 

^define AsSetIndex(row* col) (((row) * aBoardSize) + 

(col)) 

^define SetKemberRow{member) ((member) / gBoardSlze) 

tfdeflne SeLMeinberCol [member) ((member) % gBaardSize) 

^define Cel 1 Value{row,col) (eBoard[(row)*C&RosrriSjzc) + 

(col)]) 

InitVts 

// alloc set list 

static void InitSetsO I 

gSetAlloc ■ 1000; /f will gniw a? needed 

gSotHandle = KewHandle(sIxeof(Sot) * gSetAlloc); 

nLoek(gSetHtmdie); 

gSets = (Set *J *gSetllandie; 

gSetCount = D; 

gTouchedCount ^ 0: 

1 

IhspiMieSctfi 

static void PiuposeSetsO I 

DisposeHandle(gSetHandie): 

[ 

NoteSetAdded 

// set has been addet!, so it needs to be el’^t■ek^xl ftir simplicJtion 
static void NoteSerAdded(Ini s) I 
if (gTouchedCount < klstaekSlze) 

gTouchedStack lgTouchedCount++J * s: 

I 

NoieSctReduecd 

// set lra.s been retiuctxl.so it netxLs to be cluxketi for simplii'ation 
sialic void l4oieSeiRedueed( iril ii) I 
int i; 

for (i = 0; i < gTotichedCount: i++) I 
if fgTouched^tackll 1 = s) 

return; // already thea'. so doni add 
I 

if (gTouchedCount < kStackSlze) 

gTouehedSt nc k (gTouehrdCount ++ ] " u; 


ftjpTouthed 

// remove a set to lx; cheeked 
static int PopTouehedO \ 
if (gTouchedCounr > 0) 

return gToiiehedStackf-gTourhedCoustl; 
return 0; 
t 

NoteViRcjilaced 

// set has Iwen a'plaeed by ariotlu^r, so a!iy tieeuiteiiee 
// of Inim’ SCI need to tic changed. 

static void HoteSetHeplacedfint from, int to) I 
Int I; 

for (i - 0: I < gTouthedCoutit : i++) I 
If (gTouchedStack(i ] = tol ( 

gTouchedStack111 ■ gTouchedStackIgTouchedCouni 

Ij: 

gTouchedCount 1: 
i “ 1: 

I 

pise if fgTotirhodSiaek [ i 1 “ fun*) 
gTouehedStucklil * to; 

I 

I 
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The view from the top 



The possibilities are limitless with JBuilder, the leading Java'* development 
solution. 


Borland 


Take EJB development to the nert level with an intuitive visual designer. 
Rapidly develop and deploy J2£E“ e-business applications to multiple 
application servers including Borland* Enterprise Server^ BE A* WebLogtc,® 
IBM* WebSphere^* and iPlaneE^ Application Server. Develop and deploy 
applications on Windows * Linux^® Solaris,'^ and Mac* OS platforms. Efficiently 
collaborate as a team with support for leading version control systems. Build 
data-driven Web applications using servlets, JSP/** and XML. 


View code in a dramatic new way with UML code visualization. Experience 
extreme productivity with refactoring, unit testing, and documentation tools. 

See for yourself at http://www,borland.com/new/jb6/5064,html 



HI HM m 



nwm 

AWaRDS 



Hill 

iKognOniGVmMa 


in BoHand ' OSiJOl Bcflaiid SoUwnre CorporatJqn. All rtitrved. All Bo*-land bMucl amH preidijct tiJimK are trademarha or registered iradeniurks of Borliiini Sollware CdrjMralioii in the United Stistra ^ind 

Dlbcr tduiilrtes. Java and ail marks are trademarks or registfifett trarfomflrks of Son Miti-Dsysicimi, Inc. in tht L.S. and other countries. All other marta are l\m Ftrspin'l^ of Uieir renjectiw owners. ^ 12429.7 













SimpHfySuhscts 


^define kEquai 0 
kSubset I 

#deflnfl kSuperftet Z 
iideffni^ kniiijoiiit 3 

(>>mpatvScts 

// cam pun- scts; aigm t i|ual. sulm, Mjpcnici, ur disfoini 
static Int CompareSetsCSet * a* Set ’ b) \ 
int * ap ^ aOtteaibers: 
itit * bp - b->metiibers: 
itit * afsnd *= ap + ft->i!ioinberCount: 
int * bond * bp + b >P!GinberCount: 

Int anit but: 

If (a >meabotCouiit ^ b’>iiietiiberCount 
a->boinbGount b->boiibCount) I 
// niny be tijuul 

vhiie (ap 1“ send && bp != bend) I 
am “ *aptl; 
bm - *bpfl; 
if (am J" bm) 

reLuni kDiajoint: 

If (up T” aend || bp != bend) 
return kDisjoint: 
return kEqual: 

1 

else if (a->memberC<iurit > b >8ieaberCount 

a >bo«bCoutit >= b HombCount) I 
// may be supcrsci 

while (ap != aend bp != bend) I 
am - *ap++: 
bm * *bp-H-: 

while (am < bm && ap 1'^ aend) 
am = *ap++: 
if (am I"' bm) 

reiurn kDisjoint; 

1 

if (bp 1= bend) 

return kDisjoint: 
return kSuperset: 

I 

nine if (a >momberGount < b >niemberCount lnh 

a > bomb Co Lint C= b->bonibCount) I 
// ntJiy Ih' subset 

while Up 1= aend bp I* bend) I 
am “ *ap++: 
bra - *bpf+: 

while (am > bm hit bp bend) 
bm " 'bp-H-; 

If tam !* bm) 

return kDisjoint: 

I 

if (up I" aend) 

return kDisjoint: 
return kSubset: 

) 

else 

return kDlnJoint: 


Subtr.iaSct 

// ;i = *1 b; b initst In* vt pnipcr subset uf a 
static void SubtractSet(Set * a. Set * b) ( 
int * apl “ a->raembers: 
int • ap2 ^ a->ri3embers: 
int * bp - b Omembera: 
inr * send npi + a >iiie(iiberCount: 
ini ’ bend = bp + b->mcmberCount: 
int m, bm: 
whi le (bp bend) t 
am * •ap2’H: 
bm “ ‘bpH i 

while (am < bm hh up2 1= send) I 

'opt++ am: 

am “ *ap2++: 

I 

1 

while (ap2 I*" aend) I 
•aplM = *ap2++: 

I 

a ^memberCouni b->meiiberCount: 
a >bombCouni b'>bombCQunt: 


I 


// dicck the modiikd set ait^iinst all oiheis. 

// Rtmovr if it L-i equal lo one. 

U If it his a jiubset or superset, 

// replace the superset with the difference between the sets, 
sraric void SlmpH fySubsetirfSet ‘ modifiedSet) I 
Int s: 

Set * set = gSets: 

Int answer: 

for (e “ 0: s < gSetCounti » set ( 
if (set “= modlfiedSet) 
continue: 

answer ■= Compa reSeta (sol, modlfiedSet): 
if (answer kEqual) I 
gSelCoutit 1: 

*set gSets [gSetCountJ: 

NoteSetRepiaced{gSetCount. s); 
break: 

J 

else If (nnawer ” kSubnnt) I 

Huht ract Sot(modifiodSot. sot): 

NoteSetRoduced(modiliedSet - gSets): 

1 

else if (answer = kSuporset) I 
SubtractSet(set, modifiodSet): 

NotoSetReduced{iret - gSetn); 

I 
I 
I 

Simplih’Sets 

// Ainiplify all sets tlial liave Ih'cii umlied 
static Boolean SimplifySetKO 1 
if (gTotichedCount 1” 0) I 

while (gTouchedCount !* 0) 

Simpl IfySubsecsfSgSois lf*opTouchedO ]): 
tettirn irue: 

I 

return false: 

I 

FintlSi'tMf'mlx'rr 

// iintl Ute Riven cdl in the gbrn set; 

// fLium 4 if not foundH otherwise a t urn intK'x 
static int t'iadSet Member (Set ' set. int member) I 
Int cellCount « set->membGrCount: 
int * ceils “ 3et‘>mcmbers: 

//nxme — use binary' st-aah for lar^srr sets 
int lu = 0: 

if (member >- cellnfcol1 Count/2l) i 
m conCount/2: 
cells += m: 

1 

for (: m < ceilCount: int+, eells++) ( 

If (member “ 'cells) 
return rai 

if (member < 'eells) 
break: 
t 

return 1: //noi found 

J 


AlkjcSet 

// tuiikc sua* thca- is space Idr iiioihcr set 
static * All nr Sot C) I 

if (gSetCount >= gSetAlloc) [ 

// need to alka'^te nioa si,ns 

gSetAlloc = gSetCotint '1/2: 

HOnlock(gSetHandle): 

SeiHandleSizeCgSetflandle. siaeof(Set) ' gSetAiloe); 
if (MemErrorO !- tioErr) t 

prlntfC-\n\nTRO[mhR HiSTER OUT OF 

HRM0RY\n\n‘‘): 

gOumeOvet = true: 
gSetCounc /= 2: 

] 

HLock{gSetHandle): 

gSets * (Set ') 'gSetHandle: 

I 

gSerCount += 1; 
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I’d rather create clocks than invoices. 

If I wanted fo keep books all day, rd have been an accountant. 



Small Business. 


MYOB software is the simplest, most powerful, most complete 
solution for managing my company on the Mac, from the day to day 
to the bottom line. 


Smart Solutions.^" 

AccountEdge on th© JVlac. ^ 
Software [nclifdes Quick Books" eon version 
utility. MYOB also offers conversion service. 

800.32 2,M YOB 
in yob, corny US 


Antique frames. Quartz movements. ThaVs my business. 

MYOB software works for me. 


Is.ft imriattsa^k ol Intuii, tnc. 








rc*urn fcgStfis[gSetCcitiiit - i}: 


AtldNcwSet 

// M 4 set fuf itii: newly revealed eell, being atre 

// U) add neighbtir cdL'i in tjrder index valw 

static Set * AdrfMewSettlnt rov^ Int col, ini bombCount) i 
Set * set ^ AllocSoU); 

// whether this tnangji' is np tjr tUmn ptiinting: 
ini down = (Uow+col) & 1): 
itit up ' ! ' down: 

Int r: 

Int c; 

int do, chi; 

Int ‘memp set->inembers: 
int Index; 

// n>w above iriangk- 
tf (row f- 0) f 
t = row ‘ 1; 
do “ col ' I ■ down; 
if (do C 0) 
do ^ 0; 

chi “ col 1 + down: 
if (chi >- gRoatdSlsieJ 
ehl * gHoardSi^^e - 1: 
index ” AsSetIndex(r, do) : 
for (c = do: c <*^ chi: c-t+, indpxi+) I 
int value “ gBoard[Index]: 
if (value = kllnknown] 

•ftetnpt-t - Index; 
else If (value " kBumbl 
boiibCourii = 1: 

I 

I 

// row Ilf ihb cell 
t ^ tow: 
c]o * cd ■ 2i 
If (do < 0) 
do • 0: 
cbi - col + 2; 
if tchl >- gBoardSl^e) 

chi ^ gBoardSlze - I; 
index • AsSetIndexCr, clo); 
for (c do; e chi: r++, index'H-) [ 

Inf value • gftoard [IndexJ: 

If (value == kUnknown) 

*ineap++ = index: 
else if (value = kSomb) 
bonbCount -- I: 

1 

// row below 

If (row I” gdo^trdSixe - 1) I 

r * row + 1: 

do ^ col - 1 up: 

if (do < 0) 

d o 0: 

chi ccl t 1 i up: 

If (chi >“ gBoardSixe) 

chi ' gHoardSi:se li 
index ^ AaSetlTidexIr, do): 

Cor (c ^ do: c <” chi; c-H. index* t) \ 
int value * gBoard[index]: 

If (value “ kUnknown) 

'menip** = Index: 
dse if (value ” kRottib) 


set - WaiberCount ^ menip - Eet->aenibers: 

set->bombCount - boabCount: 
if (set >11 era her Count = C) ( 

// eantel Ihc add 
gSerCouni; - 1; 
sei ^ 0: 

1 

return set: 


// helps hen* Thar 5cT uses sanic inckx tliai Iwiard docs. 

// so it's fflk-icnt to Imik op cell in biiard. 
static Boolean CleanSetsO ( 

Boolean cleaned * false: 
int s: 

Set * set ” gSets: 

for (s = 0: s < gSetCount; s++, set ++J t 
int • pi set >menbers: 

Int * p2 ” set >Benbers: 

int * end = pi + Get ^aembetCeunt: 

int member; 

int value - kUnknown: 

// thn>ugli mcnilicrs until a irvcak-il <mc is foiiml 
while (p2 end) I 
aemhef = 

value " gBoardimemberI: 

If (value = kUiiknown) 
pi += 1: 
dee f 

set->Diifij!iberCoiint 1: 
cleaned “ trun: 

If (vnltie ** kiomb) 

sei >bontbCourit " 1: 
break; 

I 

i 

// copj' mcmlH*r> afitr any ncvcaJcd mt mhcr^ 
while (p2 1= end) I 
member “ *p2++; 
value ^ gBnardtmemberJ: 
if (value = kUnknown) 

*pl++ “ member: 
else I 

seC'>iieraherCount 1: 
cleaned true; 
if (value khomb) 

set IhombCouru “ 1: 

1 

I 

I 

return cleaned; 

I 

t IpdiUcNcts 

// add jici (of new cell 

static void UpdeteSetalint rown int col) I 
char value = CeilVa ltie( row. COl); 
if (value kBoatb) f //valiK=5n 
// aiid a new' set for this info 

Set ‘ set * AridNewSr't (row, cd, value): 

If (set 0} 

Nat cSe L Ad de d|seI gSet s): 

I 

MovcAntk ipiknc 

// makes a move: via tailback ;uul addv set If nircssaty 

static void HoveAndUpdateflnt law* hit col, Boolean 

checkOrMark) I 

Boolean yonlose =* false: 

Boolean yoiiyin = false; 

1[ (gCameOver) 

retur n: tl ganir almudy over 

gKakeHovefrow, col, ^igBoirihFiHrmainltig, chcckOrHmk, 
4youLose, 

kyoiiWIti ); 

gUnknownBemniinliig = 1 : 

If (youLose || youWln) 

gGaweOver = true: //tofscape mam kmp 

else 

UpdateSets(row, col): 

1 

lixpliHcNardy 

// make safe moves. Thai is. kitown Ixifiiiia and known non-t>onibs. 
sialic Boolean ExpioreSafely() I 
Boolean explored false; 
int s: 

Set * set ^ gSets; 


LTcanSets for (s ” 0; s < gSetCount;) ( 

// rciiMivv aJrt'ady nrvtaltt! cells from all sets; // safe to cxpltirc if dthtr no Immlis or all Ixmilw 
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Tips, Tricks, 
and Sage Advice 

for Your Mac 


30% off 
these Mac 
titles at 


BORDERS’ 






Amrtrii 


Mac 911 
Chris Breen 

352 pages *0 201-77339-2 
Retail Prices $29.99 
Borders Price: S20.99 


Cocoa Programming for 
Mac OS X 
Aaron Nillegass 
416 pages •0-201-72683-1 
Retail Price: $44.99 
Borders Price: S31.49 



Mac OS X Advanced: 
Visual QukkPro Guide 
Marta Langer 
312 pages* 0-201-74S77-1 
Retail Price: S24SS 
Borders Price: $17,49 



The Macintosh Bible, 8th Edition 

Clifford Colby and Marty Cortinas, Eds. 
9B4 pages • 0-201-70899-X 
Retail Price: S34.99 
Borders Price: S24.49 


Macintosh..,The Naked Truth 
Scott Kelby 

240 pages *0-7357-1284-0 
Retail Price: $19.99 
Borders Price: $13.99 



Complete Idiot^s Guide to 
Mac OS X 
Kate Binder 

384 pages *0 7897-2528-2 
Retail Price: $19.99 
Borders Price; $13.99 


*30% off these select titles 3/24/02 through 4/28/02. 


A 

ALPHA 



Ptiddtiijl FKSt 


A 

rr 


Addison 

Wealey 



BORDERS* 


B00KS*MUSIC«M0VIES*CAFE 































* ^ 

Made with 



REALbasic® 


REAL Software and MacTech present tlie REALbasic Showcase to 
highlight some of the fantastic solutions created by REALbasic users 
worldwidc.Tlie showcase illustrates the wide range of applications that 
developers using REALbasic can create. Some benefit any Mac user, and 
others are more specific. All of them are seriously cool! 

REALbasic is the powerhil, easy-to-use tool for creating your own 
software for Macintosh, Mac OS X, and Windows. It runs natively on 
Mac OS X as well as earlier versions of the Mac OS. For more 
information, please visit: <www.realbaslc.coin>. 

Tire Made with REALbasic program is a cooperative effort between 
REALbasic users and REAL Software, Inc. to promote the products 
created using REALbasic and the people who create them. For more 
information about the Made with REALbasic program, please visit: 
<www.realbasic.com/realbasic/mwrb/Partners/IVIwRbProgram.html>. 










REALBASiC SHOWCASE 


Extend REALbasic with 
Advanced Plugins 

Spreadsheet Controls: 

We provide a wide lange of spreadsheet controls for 
REALbasic. including multistyled and custom rendering 
spreadsheet controls- 



* More than 32k of rows. 

* Classic, OS X and Win32, 
•Accelerated for maximum 

speed. 

* Images in cells. 


Cryptography: 

Si ^j'C We provide data encryption, encoding, 

compression and hashing for REALbasic. 

OMg£io Supported Algorithms: 

• Encryption: 

- e-CryptIt 

• BlowFish (446 bit) 

-AES (Rijndael) (256 bit) 

• Encoding: 

• e-CryptIt Flexible 

- Base 64 

- BinHex 

• MacBinary III 

• AppleSingle / Double 

- UUCoding 

• Compression: 

- Zip on Strings and streams (.gz) 

• Hashing and Checksums: 

- CRC32 / Adler32 
-MD5/HMAC MD5 

-SHA/SHA1 /HMAC SHA1 


Other Plugins: 

We have many other 
plugins for REALbasic, 
including plugins to do 
advanced MacOS 
Toolbox tasks and more 
custom Controls. 



Speed up developement and make 
more advanced applications 
by using plugins I Get free demos 
at www.einhugur.com 



Einhugur Software 
sales@einhugu r. com 
www.ein h ugur.com 


Corona 

accounting software 


"Easy to set up, easy to use, 
and excellent support from 
the developer." 

Five stars on VersionTracl^r.com 

• account chart 

• address index 
• help facility 

$49-95 

Free 30'day trial 

http: / / h o mepage. mac.com / id le\rild/ Corona US. hqx 


A best friend for business! 

p o. boxSlSd « riewterg * oragon • 97132 
ldl9wlli;H|mac.coni 






Picture 

Play 


Create digital image compositions on 
your Mac, quickly and easily. 


P 

1 


..'ll! 

For more Information, 
email chris@cre5cendosw.com, or 

visit us today at www.crescendosw.coml 
























































REALBASIC SHOWCASE 



db Reports 


Printing database driven reports 
from your REALbasic project has 
never been easier. 

Download your free demo today. 

http; // abDataTools.com 


ld^lElAYI)V@l£ilEl%3 

CHT SLCEP DESISN 

FontVIewer 


FontViewer is a simple but elegant foot viewer that allows you to 
preview all fonts in your fonts folder They con be displayed in 
various sizes and styles with the click of o mouse. FontViewer also 
features the ability to display your fonts in o slideshow, and view 
your fonts in almost every type of environment possible (ie 
desktop, menus, icons, etc.) 

Creotive Box URL: http://www,creativebox,net/ 
Developer e-mail: ja5on@creatrveboxmet 



pi Dock 


piDock is the must have navigation and launching utility for 
AlacOS. Now you can easily organize, navigate and hunch 
files with o simple sweep of the mouse. 

Compatible with OS 8.6 through 10.1, OSX users can now 
control-option click a folder to navigate iVs contents. 

http://www.pidog.com • http;//www.pidock.€om 
piDock@pidog.com 










iScr^nsaver ' 
designer 

for Macintosh and Windows 



Mac designers 

btjiki pmtessionQt screensavers 
a Miidbm rndduvie 


the world's only cross-platform 
screensaver design tool 


• build both Macintosh and windows screensavers 
with a single dick^ on whatever system* you are using/ 

• use any QuickTime movie format : 

Macromedia Flash, MPEG, Cinepak, MP3, Midi, AVI, DV Video.., 

• include a hidden movie that can be unlocked 
with a registration code 

• customize and fully-brand both Installers 
and Screensaver control panels with pictures and text 

• screensavers install without DLLs, extensions, or restarts 


simple 

WYSIWYG 

editor 

supports 
interactive Flash 
and QuickTime 


consistent 
cross-platform 
user interface 


try before you buy 
fully functional 
online downloads 


http .‘/iScreensa ver. net 

email: info # iScreensaver.net 


a-v. 



ivV HlMfifV MVVwin 
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REALBASK SHOWCASE 



StimpSoft™, Inc. 


SfimpSoh^^ Inc. Makers of insanely 
mediocre software for cats, dogs, voles, 
wolhbies, mangos, crickets, and 
people. We put the "i" /n ^Software^. 

URL; http;//www.stimpsoft.com 
Email: jahn@sHmpsoff.com 



DBIxaDOSQ 


Are you looking for extremeiy small out-of-pocket advertising 
that will reach your target audience? 

We will bull you for ads monthly as each issue ships! 
Contact our ad sales team today for more details! 

Voice: 805/494-9797 xl 13 * e-Maii: adsales@mactech.com 


wvvw.mactech.com 



MAC MUSIC MANAGEMENT FOR^ 
SONY" 5 TO 400 DISC CD CHANGERS 


Control up to T2 changers (4,800 music CDs) v 
Control Any Brand Stereo Receiver 
u Play MP3 and other Sound Files 
;;i. Plus much, much more!!! 


www.titletrack.com info@titletrack:com 


Whistle Blower 

Enterprise server monitor and restort utility 
whistleblower.sentman.com 

Connect to and validate the response from web servers, 
cgi scripts and over 23 other types of servers. 

Send email, pages and perform unattended restarts via 
MasterSwitch or PowerKey. 

Shifts moke sure that the person on coll when rfie server 
goes down is the one who gets the page. 

68k, PPC and Carbon 

Web based administration lets you check on and restart 
your servers from anywhere. 

Customize your response to an outage with Apple Script 

emoil US at whistlebiower@sentman.com 














































Tlic below news licailUnes recently ensssetl our news desk* For more information on 
each of these ttems, cheek out the MacTcch web site <littp://wTvw.maetech.com> and 
search t)ui the IhtIow lieadltnes from the home page. 


• Bains Software Releast^s New 
Versions of MacDICT and 
Snapper! leatl 

• bit Vice MFHG2 vkle(» enecKler: 

rf >fes,s i (>na I I )et'od i ng, Consii me r 
Piice 

• Trinfinity Releases 'l ime 'rniek 1.1 For 
Maciniosh And Windows 

• Runtime Ships Revolution FLC 
Pricing 

• Iceblink Sofiw'ari' Relea.sc'S 
[infolBalciter Classic 

• PC-Mac-Net KileShare vl .5 
Streamlines File Transfers 

• Now Mp-u>-Date ^4 Contact 4.2: 

OITits Ikickup anil New' Palm 
Support 

• Vidn>(^lix 2.0: Building in IntcTUCtive 
Objects 

• Freakin' Magic for FileMaker Fro: 
Acx'elerate your il) WebSTAR 

• SambuCLis v2.0.tJ: I'ime Management 
Application 

• Snard vKO Releii.setl 

• Radio Foster FO 

• Aladdin Ships Secure Delete- llie 
Digital Dfx-unicni Slireddcd 

• /TRANSIT v2,0 dc|>Ioys ColdFusion 
applications to Mac OS X 

• Mac OS X Application allows 
Scripted Control of FrontUase 
Data Ba.se 

• FileMaker Units Top 7.S Million 

• Markzwarc Announces Quark S.O 8c 
ItiDesign 2,0 Sup]>ort 

• eSellenite Supporrs UKALhasit^ 
Development For Windows 

• Lasst>Sitesx’om 

• St. Clair Softw'are Uptlates Default 
Folder X 

• Dragon Bum: New CD-Recordtng 
Software for Mac 

• WestCtv releases Uayoiit Master \A 
HTMI. + OSS web page layout 

• FILTERiT 4.t.J 

• MACWHilCOM - Falo Alto Mac 
Server Colcx:alion Continunily 

• Cfioss-Flaifonii HELP Engine for Your 
RI'ALbasic Apps 


• Precision Plugin l*S for RFALhasic, now 
with x86 support 

• Znippeiizer-X version 1,4 

• M a ssTra ns it Gains Improved Fncryption 
and Security Capabilities 

• Fresenta l.ld* announces iGelter 1.8 

• Colourfull Creations Releases Gilendar 
Class for KEALhasic 

• eOrdering Complete 1,0 Online Store 
and Sho[)pmg cart creator 

• Oj>enI,ink Releases Universal Sener for 
Web Services 

• Berkeley Releasees mZ. 1 li> I )SSS 
Analysis System 

• Whistle Blower 341 t<)r Mat' OS X 

• FrtdsOverload 4.1.2 lor Mac OS and 
Mac OS X Released 

• MaxBulk Mailer v2,6 

• SM*n’ Dt'ux Frttfessional v 1.1.0 
Released l)y Deep Sky IVdinolugies 

• Active Developer in v2.1(J for Mac OS X 
St*r\'er 

• Autcjlycus Annt)unces Mac OS X 
Ctiinpatihility 

• Autolycus Offers FC Spinlinage DV Fro 

• DevitrcWatcher hir InterMapiTer 
Improves Network Services Stability 

• Runtime bibs Announces Release Of 
MaeSQL 22 

• The Omni Group Ships OttiniG raffle 2.0 

• Troi Dialog Plug in 31 for FileMaker 
Fro S.5 

• Macw'orld Ct>nference ik Expo Adds 
New Conferences For New Y()rk 

• Sticky Bra in 2 

• Waves In Motion Announces Dragon 
Well Surveys / Quizzes 6,S 

• SCRlFTIt 1.0 Released (Mac and Winl 

• CDFinder 3-6 

• Advenio announces SQLGrinder 1.2 
with AppleScript support 

• ProVTfF Ships Farioraiiui iPod Organizer 

■ illymineX ujKlates Mac OS X games 

• Java-Based BlackBerry Handheld With 
Integrated Phone 

• JAW stTtwarc ships MPEG2Splitter L3 

• Global Graphics Lumches Jaw's PDF 
Server Solution 

• Ben Bird Announces BTV Fro 3,4: 
Ul>date To Macintfish Vitleo Software 




DevDepot youi source for the 
hottest new Tech Tools! 




Voice: 877-DEPOT NOW (877-337-6866) 
Outside US/Cauada: 805/494-9797 
E-mail: order 5 @dcvdcp 0 t.com 


Aj^ril 2002 • MAt.Ti'cai 





















if (set">bonibCount = 0 |[ 

set'>bombCount = set->iieHiberCount) ( 
int m: 

Boolean chcckOrMark “ set >lKiiibCoimt H 0: 

// foisc means check 
explored = true; 

for {in ^ 0; m < set->HieiftberCount: a++l I 
int laenber « setOmeabersIn]: 

HoveAndUpdate (SetMemberRowtnemher), 

SetMemberCal (tQEnber) , checkOtMark); 

// remove this set 
gSetCount * 1^ 

‘set gSets[gSetCountJ : 
NoteSetReplaced(gSetGount♦ s): 

I 

else { 

E : 

set +“ li 

I 

1 

return explored; 

1 


RndlnOthcrtka 

// ijuok fur Ukt given mcmixrr in all sets except 
// Ibr the given one. 

static int FindTnOtherSntUnt kncumHetiber, Set ‘ knownSet) I 
int Si 

Set ‘ set ** gSets; 

for {s = 0; s < gSetCount; s++. set HJ | 

Int » = FindSetHeraber(set» knownMenber J; 
if (m >“ 0 && set !■ knovnSet) 
return in: 

J 

return 1 ; 

I 


IVjylnSii 

// 1%'k n random cell I'rom the given set and reveal it. 

// set = 0 means pick fnun enire bojird of nnknowns. 
static void PrayTnSot(Set * set, Boolean checkOrMark) I 
1nt row: 

Int cut: 

if Uet = Oj t 

if (gUnknoMnRemaining < gHaKCnIl / 8) I 
// pick Jirsi unknown 
int i| 

for (i “0; i ^ gHaxCell: i-<^+) I 
if (gBoardUJ ^ kdnknown) I 

// found an unknown ceU, so tei4 il 
row " i / gBoardSixe: 
col “ i % gBoardSlse; 
break; 

1 

) 

I 

else I 

// pkk one ai Pniknii uniil an unknown is found 
while {t rue} I 

Int ceil “ randO % gMaxCell; 
if {gBoardfcrlll = kUnknown) I 
// Ibund an unknrjwn cclf so test it 
row cell / gboardSiKe: 
col ^ cell % gBoardSiKe: 
break; 

I 

I 

f 

I 

else t 

// prefer bst membcT — ((uickcsi to remove 
int m set >meiiiberCount - 1; 

// »bo prt'fer cell tliai is not withiii aiKHhiT set. 

// this that set likely has wonc ixids. 

// this is costly. I>ut it does make it more likely 
// of finding a corttci soluUcm. 
while (iB > 0 FindlnDtherSet(set- 
>meabers Iml ♦setP^O) 

M — I; 

row “■ SeLMuiiberRow(set->ineiiibets [ml); 


coi = SetHeaberColCset->BiemberEfail): 
I 

KoveAndUpdateCrov, col» chnekOrMark); 


Pray 

^define kOddsScale 40^16 

// Rnd the set with the best ixxJs for guewiing and make the guess, 
static void PrayC) I 
Set ' ptaySet " 0; 
int prayOdds = kOddaScale * 

(gUnknowiiKeiuaining - gBoitbsRanainitig) 

/ gUnknownReniflinlng: 

Boolean prayCheckOtMark “ kChecki 
iiU s; 

if (prayOdds < 0*5) ( 

prayOdds “ kOddBScele * gBmnbsReinaining / 
gUnknovnRetnalniiig: 
prayCherkOrMafk = kMutkBomb: 

I 

if (gUnknownKemaining ' 2 i gHaxCell) 

prayOdds = 0: // U>o few unkntjwn to be accurate 

for (s = Oi s < gSetCount; sil) I 

Set ‘ set - &gSets[n); 

int cells = Bet ->moH»bcrCou»ii: 

int boDibn * sot >bowbCount; 

int odds ^ kOddsScale ‘ (ceils ' bontbs) f cells; 
Boolean checkOrMark = kCheck; 
if (odds < 0*5) t 

odds = kOddsScale * bombs / cells; 
checkOrHark - kMatkBomb; 

I 

if (odds >*= pruyOdds) I 
praySel = set: 
praytldds = odds; 
prayCheckOrHark ** checkOrHark: 

1 

I 

PrayInSet(praySet, prayChockOiMurk); 


InlcrsetSeLs 

// (inurns mimbtt tif eommon mcmlxTs 
// asMimes each set luis at Iciest two meiillTcrs 

static int fntersetSetsCSuT * a. Sn * b. Set * comnon) I 
int ‘ ap = a->BiemberG: 
lot * bp = b >iiieinburs; 
int * cp ^ common >meiiberB; 
lot * aend ^ ap + a'>memberCuunt; 

Ini * bend ^ bp + b->meiiberCount: 
int am* bra; 
int n = -1: 

if (*ap > ‘(bend'i) || *bp > * Coend 1)) 
return 0; 
am 0; 
b» Ot 
while (true) f 

if {an " bill) I 
if Cn >- 0) 

‘cpff ^ ara; 
n i “ J; 

if (ap aend) 

break: 
ain = *ap-H-; 
if (bp = bend) 
break; 
bra - *bp++: 

I 

else if (am < bra) ( 
if Cap aend) 

bf eiik; 
am =" *ap^; 

I 

else if (ara > bra) I 
if (bp — bend) 
break; 
bm “ 'bp-H*; 

I 

I 

conmrDri->n]eiiiberCount ^ nr 
common‘>borabCount 1; 
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1 


roiurn n: 


1 


return true; 


RcmiJvtrlrncnitciwjn 

// Remove titc common Mibsc* fitmi A ami R, atkl ii ui a new set 

static void ReiioveIntersectiop{Sei *a. Set *b. Set * comraon) 

t 

Set * net = AllocSetO: 

*ser " •cownon: 

NuieSeiAdded(net ■ gSeta); 

SubtractSeL (a. coiamoti); 

NoteSetReduced(a gSuta); 

SubtractSet(b. ceramon}^ 

NateSetReducedlb gSets): 


Bi mimitcl tiUTSi'crioiiK 

// dinuniUc iintTscttioas thal fii a spccidc partem 
// coruii^Uig otH‘ tknsc ami tme s|>afj4t‘ set 
static Boolean KliEjiirtatelQtersocUonsI) I 
Int s; 

Set • set ® gSets: 

Set coiunon; 

if (glInkncjwnReaflining > g>lflxCeil - 10} 

rot u rn fa 1 so; // don't bother early on in game 

for Ca = 0; a < gSetCount: r++. set If) I 
If (get ^bonhCoMtit >* It 

set - >aeaibetCount sot >hfiiibCount <= 2) 

I 

// round a crowded set (eg, i bi^mbs out of 6) 

// now \m)k for an overlapping spar^ one 
int needed set->TaejDborCount ' set’^bombCount + 

1 ; 

itiL sb; 

Set * setb - gSeLs; 

for (sb “ Ol sb C gSetCounL: sb++. SPtb ++) ( 
if (setb'^boDibCoiint = I 

&& setb >nieniberCount > needed) I 
int actual * 

In terse LStn s (cot, noth.icomiaon); 

if [actual )= needed) [ 

// wc tion't have to pmy alter aU 
Keaiovelntersecl ion (sol, sotb* fiico/nmon): 


} 

\ 

) 

\ 

return false: 

I 


PkiyMiiicswccpcr 

// expioii:-, ck'an, simplih; pray 
void PlayHinesweeper ( 
int boardSi^se, 

/* number of rows/colmnns in board */ 
int niunberOfBombs, 

number of bombs in board */ 
const char 'board* 

/* board[row'boardSize f coll is board element [row»col) 

'/ 

Mine sve e p e r Hov e t* toe H a k eHove 
f* procedure for reporting moves */ 
f* MakeHove updates eleniGUts of board 

) { 

gBoardSize - boardSize: 

gRoard “ board; 

gBuQtbsRemaliTing ^ numberOfBombs: 

gUnknowiiKemalning ^ board Size ' boardSize; 

gHakeMove “ MakeHove; 

gHaxCeii = boardSize ' boardSizor 

gGaiieOver “ false; 

initSetaO: 

while (IgCaroeOver) i 

If 11Ricp]preSafelyO 

ICleanSetaO 
kh fSitnpllfySotsO 
H lEliminatelntcraocrlons() 

) I 

PrayO : 

1 

I 

DisposeSets[): 

I 


Mac^imum Mac-Talk 


Your Digital Life r. 
MacGaming... 

TechTips..^ 
Interviews... 
MacBasics... 
MacMediaPro... 


Live WED 9 - 11 PIVI 
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SuSE Linux 7.3 

• Secure 

• Stable 

• Superior 


Lfllux 


PowerPC EDITION T.J 


SuSE Linux 7.3 
PowerPC EDITION: 


Yes, please send me the power-pack... 


Please biU the following address: 




because Linux users enjoy the power and stability of SuSE Linux, 

Don’t compromise. corn^ny 


SuSE Linux 7.3 - no limits. 


Last name/Name 


Full integration with MOL 
(Mac-On'Linux) 

Scanning made easy with the 
KDE tool Kooka 

Protect your data with Soft-RAID USD 


• Great sound with ALSA 

• Surf safely with the Personal Firewall 

• Professional installation support by 
phone, fax and e-mail 

• etc. 


Phone 


Street 


Zi p-code / Postat-code 

□ SuSE Linux 7.3 PowerPC EDITION 
S 79.95 


SuSE Inc. — The Linux Experts 
580 Second St 
Oakland' CA 94607 


Order Online Today! http:// 5 h 0 p.suse.com/mt 

jnfo@suse.com (888) 875-4689 (S) (510) 628-3381 










































other software companies have customers. We’ve 
got fans. In feet MetrowerKs is the leading provider 
of development tools for the Macintosh* commu¬ 
nity. With Metrowerks CodeWarrior" tools, you 
can build powerful applications with our popular 
PowerPlant" framework, which uses industry- 
standard C-I-+. Best of all, you can create a single 
application that runs on both Classic Mac* OS and 
Mac OS X. So choose CodeWarrior tools and get 
ready to rock. 


Register now to win an iPod"* MP3 player at 
www.metrowerks.com/mactech 


metrowerks 

Softwiira- Sfnrta H*rm ^ 






e moj. Meiiuimrfks CodeMiiTiar, PnveiPfent Hct^owdlsc Jititl Utir MctibWitiff toga ife thetanutlv or regfeteiei) bafemirks ol Metnmwiriifi Oortt in lht> 

ULS. nnd^'Dr olher OMiiitnes. Macintosh and Mac an ngistBned tradeiiinilui wuf tPod it n trnrittmflhtt of A^e ConifMitei, Inc. ALL RtOinS RESERVEDl MOBOEI 1 


CodeWarrior 

Development Tools for Mac- OS 











